From 795eeb5c9993761976940e4da84f86f021e616f7 Mon Sep 17 00:00:00 2001 From: Michael Stapelberg Date: Wed, 19 Sep 2012 18:52:41 +0200 Subject: [PATCH] update /docs for 4.3 --- _docs/hacking-howto | 4 +- _docs/ipc | 54 +++++- _docs/multi-monitor | 48 +++-- _docs/testsuite | 19 +- _docs/userguide | 234 +++++++++++++++++++------ docs/debugging-release-version.html | 2 +- docs/debugging.html | 2 +- docs/hacking-howto.html | 6 +- docs/index.html.mako | 2 +- docs/ipc.html | 107 +++++++++++- docs/testsuite.html | 66 +++++-- docs/userguide.html | 261 ++++++++++++++++++++-------- docs/wsbar.html | 2 +- 13 files changed, 616 insertions(+), 191 deletions(-) diff --git a/_docs/hacking-howto b/_docs/hacking-howto index 73ae963..8a246ef 100644 --- a/_docs/hacking-howto +++ b/_docs/hacking-howto @@ -77,7 +77,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#_get_tree_reply for documentation on that and an +http://i3wm.org/docs/ipc.html#_tree_reply for documentation on that and an example. == Files @@ -141,7 +141,7 @@ src/load_layout.c:: Contains code for loading layouts from JSON files. src/log.c:: -Handles the setting of loglevels, contains the logging functions. +Contains the logging functions. src/main.c:: Initializes the window manager. diff --git a/_docs/ipc b/_docs/ipc index 83ab721..f8dfa78 100644 --- a/_docs/ipc +++ b/_docs/ipc @@ -1,7 +1,7 @@ IPC interface (interprocess communication) ========================================== Michael Stapelberg -February 2012 +August 2012 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 @@ -70,6 +70,9 @@ 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. So, a typical message could look like this: -------------------------------------------------- @@ -125,6 +128,8 @@ MARKS (5):: Reply to the GET_MARKS message. BAR_CONFIG (6):: Reply to the GET_BAR_CONFIG message. +VERSION (7):: + Reply to the GET_VERSION message. === COMMAND reply @@ -206,7 +211,7 @@ default) or whether a JSON parse error occurred. { "success": true } ------------------- -=== GET_OUTPUTS reply +=== OUTPUTS reply The reply consists of a serialized list of outputs. Each output has the following properties: @@ -270,12 +275,15 @@ border (string):: Can be either "normal", "none" or "1pixel", dependending on the container’s border style. layout (string):: - Can be either "default", "stacked", "tabbed", "dockarea" or "output". + Can be either "splith", "splitv", "stacked", "tabbed", "dockarea" or + "output". Other values might be possible in the future, should we add new layouts. orientation (string):: Can be either "none" (for non-split containers), "horizontal" or "vertical". + THIS FIELD IS OBSOLETE. It is still present, but your code should not + use it. Instead, rely on the layout field. percent (float):: The percentage which this container takes in its parent. A value of +null+ means that the percent property does not make sense for this @@ -296,6 +304,11 @@ window_rect (map):: geometry (map):: The original geometry the window specified when i3 mapped it. Used when switching a window to floating mode, for example. +window (integer):: + The X11 window ID of the *actual client window* inside this container. + This field is set to null for split containers or otherwise empty + 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. focused (bool):: @@ -526,6 +539,35 @@ urgent_workspace_text/urgent_workspace_bar:: } -------------- +=== VERSION reply + +The reply consists of a single JSON dictionary with the following keys: + +major (integer):: + The major version of i3, such as +4+. +minor (integer):: + The minor version of i3, such as +2+. Changes in the IPC interface (new + features) will only occur with new minor (or major) releases. However, + bugfixes might be introduced in patch releases, too. +patch (integer):: + The patch version of i3, such as +1+ (when the complete version is + +4.2.1+). For versions such as +4.2+, patch will be set to +0+. +human_readable (string):: + A human-readable version of i3 containing the precise git version, + build date and branch name. When you need to display the i3 version to + your users, use the human-readable version whenever possible (since + this is what +i3 --version+ displays, too). + +*Example:* +------------------- +{ + "human_readable" : "4.2-169-gf80b877 (2012-08-05, branch \"next\")", + "minor" : 2, + "patch" : 0, + "major" : 4 +} +------------------- + == Events [[events]] @@ -621,7 +663,7 @@ C:: Ruby:: http://github.com/badboy/i3-ipc Perl:: - http://search.cpan.org/search?query=AnyEvent::I3 + https://metacpan.org/module/AnyEvent::I3 Python:: - https://github.com/whitelynx/i3ipc - https://github.com/ziberna/i3-py (includes higher-level features) + * https://github.com/whitelynx/i3ipc + * https://github.com/ziberna/i3-py (includes higher-level features) diff --git a/_docs/multi-monitor b/_docs/multi-monitor index d3f31ba..a1fd6dc 100644 --- a/_docs/multi-monitor +++ b/_docs/multi-monitor @@ -1,17 +1,14 @@ The multi-monitor situation =========================== -Michael Stapelberg -July 2012 +Michael Stapelberg +September 2011 …or: oh no, I have an nVidia graphics card! == The quick fix If you are using the nVidia binary graphics driver (also known as 'blob') -you need to upgrade to at least version 302.17 (released in June 2012). - -In case you cannot update the driver to 302.17 or newer on your machine for -some reason, use the +--force-xinerama+ flag (in your .xsession) when starting +you need to use the +--force-xinerama+ flag (in your .xsession) when starting i3, like so: .Example: @@ -23,15 +20,15 @@ exec i3 --force-xinerama -V >>~/.i3/i3log 2>&1 == The explanation -Starting with version 3.ε (March 2010), i3 uses the RandR (Rotate and Resize) -API instead of Xinerama. The reason for this, is that RandR provides more -information about your outputs and connected screens than Xinerama does. To be -specific, the code which handled on-the-fly screen reconfiguration (meaning -without restarting the X server) was a very messy heuristic and most of the -time did not work correctly -- that is just not possible with the little -information Xinerama offers (just a list of screen resolutions, no identifiers -for the screens or any additional information). Xinerama simply was not -designed for dynamic configuration. +Starting with version 3.ε, i3 uses the RandR (Rotate and Resize) API instead +of Xinerama. The reason for this, is that RandR provides more information +about your outputs and connected screens than Xinerama does. To be specific, +the code which handled on-the-fly screen reconfiguration (meaning without +restarting the X server) was a very messy heuristic and most of the time did +not work correctly -- that is just not possible with the little information +Xinerama offers (just a list of screen resolutions, no identifiers for the +screens or any additional information). Xinerama simply was not designed +for dynamic configuration. So RandR came along, as a more powerful alternative (RandR 1.2 to be specific). It offers all of Xinerama’s possibilities and lots more. Using the RandR API @@ -41,16 +38,17 @@ workspaces to output names instead of some rather unreliable screen identifier As RandR has been around for about three years as of this writing, it seemed like a very good idea to us, and it still is a very good one. What we did not -expect, however, was the nVidia binary driver. It did not support RandR until -mid 2012, even though nVidia had announced that it will support RandR -previously. What does missing RandR support mean for you? First of all, you are -stuck with TwinView and cannot use +xrandr+. While this ruins the user -experience, the more grave problem is that the nVidia driver not only does not -support dynamic configuration using RandR, it also does not expose correct -multi-monitor information via the RandR API. So, in some setups, i3 will not -find any screens; in others, it will find one large screen which actually -contains both of your physical screens (but it will not know that these are two -screens). +expect, however, was the nVidia binary driver. It still does not support RandR +(as of March 2010), even though nVidia has announced that it will support RandR +eventually. What does this mean for you, if you are stuck with the binary +driver for some reason (say the free drivers don’t work with your card)? First +of all, you are stuck with TwinView and cannot use +xrandr+. While this ruins +the user experience, the more grave problem is that the nVidia driver not only +does not support dynamic configuration using RandR, it also does not expose +correct multi-monitor information via the RandR API. So, in some setups, i3 +will not find any screens; in others, it will find one large screen which +actually contains both of your physical screens (but it will not know that +these are two screens). For this very reason, we decided to implement the following workaround: As long as the nVidia driver does not support RandR, an option called diff --git a/_docs/testsuite b/_docs/testsuite index 720ff39..4dcf167 100644 --- a/_docs/testsuite +++ b/_docs/testsuite @@ -1,7 +1,7 @@ i3 testsuite ============ -Michael Stapelberg -September 2011 +Michael Stapelberg +September 2012 This document explains how the i3 testsuite works, how to use it and extend it. It is targeted at developers who not necessarily have been doing testing before @@ -33,6 +33,19 @@ able to easily test if the feature is working correctly. Many developers will test manually if everything works. Having a testcase not only helps you with that, but it will also be useful for every future change. +== Relevant documentation + +Apart from this document, you should also have a look at: + +1. The "Modern Perl" book, which can be found 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 +3. The latest documentation on i3’s IPC interface: + http://build.i3wm.org/docs/ipc.html + == Implementation For several reasons, the i3 testsuite has been implemented in Perl: @@ -45,6 +58,8 @@ For several reasons, the i3 testsuite has been implemented in Perl: 2. Perl is widely available and has a well-working package infrastructure. 3. The author is familiar with Perl :). +4. It is a good idea to use a different language for the tests than the + implementation itself. Please do not start programming language flamewars at this point. diff --git a/_docs/userguide b/_docs/userguide index 4145279..2214f01 100644 --- a/_docs/userguide +++ b/_docs/userguide @@ -1,11 +1,11 @@ i3 User’s Guide =============== -Michael Stapelberg -April 2012 +Michael Stapelberg +August 2012 This document contains all the information you need to configure and use the i3 -window manager. If it does not, please contact us on IRC (preferred) or post your -question(s) on the mailing list. +window manager. If it does not, please check http://faq.i3wm.org/ first, then +contact us on IRC (preferred) or post your question(s) on the mailing list. == Default keybindings @@ -61,16 +61,18 @@ windows. TODO: picture of the tree -To split a window vertically, press +mod+v+. To split it horizontally, press -+mod+h+. +To split a window vertically, press +mod+v+ before you create the new window. +To split it horizontally, press +mod+h+. === Changing the container layout A split container can have one of the following layouts: -default:: +splith/splitv:: Windows are sized so that every window gets an equal amount of space in the -container. +container. splith distributes the windows horizontally (windows are right next +to each other), splitv distributes them vertically (windows are on top of each +other). stacking:: Only the focused window in the container is displayed. You get a list of windows at the top of the container. @@ -78,8 +80,8 @@ tabbed:: The same principle as +stacking+, but the list of windows at the top is only a single line which is vertically split. -To switch modes, press +mod+e+ for default, +mod+s+ for stacking and -+mod+w+ for tabbed. +To switch modes, press +mod+e+ for splith/splitv (it toggles), +mod+s+ for +stacking and +mod+w+ for tabbed. image:modes.png[Container modes] @@ -196,20 +198,21 @@ image::tree-shot4.png["shot4",title="Two terminals on standard workspace"] It is only natural to use so-called +Split Containers+ in order to build a layout when using a tree as data structure. In i3, every +Container+ has an -orientation (horizontal, vertical or unspecified). So, in our example with the -workspace, the default orientation of the workspace +Container+ is horizontal -(most monitors are widescreen nowadays). If you change the orientation to -vertical (+mod+v+ in the default config) and *then* open two terminals, i3 will -configure your windows like this: +orientation (horizontal, vertical or unspecified) and the orientation depends +on the layout the container is in (vertical for splitv and stacking, horizontal +for splith and tabbed). So, in our example with the workspace, the default +layout of the workspace +Container+ is splith (most monitors are widescreen +nowadays). If you change the layout to splitv (+mod+l+ in the default config) +and *then* open two terminals, i3 will configure your windows like this: image::tree-shot2.png["shot2",title="Vertical Workspace Orientation"] -An interesting new feature of the tree branch is the ability to split anything: -Let’s assume you have two terminals on a workspace (with horizontal -orientation), focus is on the right terminal. Now you want to open another -terminal window below the current one. If you would just open a new terminal -window, it would show up to the right due to the horizontal workspace -orientation. Instead, press +mod+v+ to create a +Vertical Split Container+ (to +An interesting new feature of i3 since version 4 is the ability to split anything: +Let’s assume you have two terminals on a workspace (with splith layout, that is +horizontal orientation), focus is on the right terminal. Now you want to open +another terminal window below the current one. If you would just open a new +terminal window, it would show up to the right due to the splith layout. +Instead, press +mod+v+ to split the container with the splitv layout (to open a +Horizontal Split Container+, use +mod+h+). Now you can open a new terminal and it will open below the current one: @@ -235,6 +238,24 @@ windows will be opened to the right of the +Vertical Split Container+: image::tree-shot3.png["shot3",title="Focus parent, then open new terminal"] +=== Implicit containers + +In some cases, i3 needs to implicitly create a container to fulfill your +command. + +One example is the following scenario: You start i3 with a single monitor and a +single workspace on which you open three terminal windows. All these terminal +windows are directly attached to one node inside i3’s layout tree, the +workspace node. By default, the workspace node’s orientation is +horizontal+. + +Now you move one of these terminals down (+mod+k+ by default). The workspace +node’s orientation will be changed to +vertical+. The terminal window you moved +down is directly attached to the workspace and appears on the bottom of the +screen. A new (horizontal) container was created to accomodate the other two +terminal windows. You will notice this when switching to tabbed mode (for +example). You would end up having one tab called "another container" and the +other one being the terminal window you moved down. + [[configuring]] == Configuring i3 @@ -273,11 +294,21 @@ a # and can only be used at the beginning of a line: # This is a comment ------------------- +[[fonts]] + === Fonts -i3 uses X core fonts (not Xft) for rendering window titles. You can use -+xfontsel(1)+ to generate such a font description. To see special characters -(Unicode), you need to use a font which supports the ISO-10646 encoding. +i3 has support for both X core fonts and FreeType fonts (through Pango) to +render window titles. + +To generate an X core font description, you can use +xfontsel(1)+. To see +special characters (Unicode), you need to use a font which supports the +ISO-10646 encoding. + +A FreeType font description is composed by a font family, a style, a weight, +a variant, a stretch and a size. +FreeType fonts support right-to-left rendering and contain often more +Unicode glyphs than X core fonts. If i3 cannot open the configured font, it will output an error in the logfile and fall back to a working font. @@ -285,11 +316,13 @@ and fall back to a working font. *Syntax*: ------------------------------ font +font xft: ------------------------------ *Examples*: -------------------------------------------------------------- font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1 +font xft:DejaVu Sans Mono 10 -------------------------------------------------------------- [[keybindings]] @@ -315,10 +348,15 @@ your bindings in the same physical location on the keyboard, use keycodes. If you don’t switch layouts, and want a clean and simple config file, use keysyms. +Some tools (such as +import+ or +xdotool+) might be unable to run upon a +KeyPress event, because the keyboard/pointer is still grabbed. For these +situations, the +--release+ flag can be used, which will execute the command +after the keys have been released. + *Syntax*: ---------------------------------- -bindsym [Modifiers+]keysym command -bindcode [Modifiers+]keycode command +bindsym [--release] [Modifiers+]keysym command +bindcode [--release] [Modifiers+]keycode command ---------------------------------- *Examples*: @@ -330,7 +368,13 @@ bindsym mod+f fullscreen bindsym mod+Shift+r restart # Notebook-specific hotkeys -bindcode 214 exec /home/michael/toggle_beamer.sh +bindcode 214 exec --no-startup-id /home/michael/toggle_beamer.sh + +# Simulate ctrl+v upon pressing $mod+x +bindsym --release $mod+x exec --no-startup-id xdotool key --clearmodifiers ctrl+v + +# Take a screenshot upon pressing $mod+x (select an area) +bindsym --release $mod+x exec --no-startup-id import /tmp/latest-screenshot.png -------------------------------- Available Modifiers: @@ -434,7 +478,8 @@ workspace_layout tabbed === Border style for new windows -This option determines which border style new windows will have. +This option determines which border style new windows will have. The default is +"normal". *Syntax*: --------------------------------------------- @@ -446,6 +491,22 @@ new_window new_window 1pixel --------------------- +=== Hiding vertical borders + +You can hide vertical borders adjacent to the screen edges using ++hide_edge_borders+. This is useful if you are using scrollbars, or do not want +to waste even two pixels in displayspace. Default is none. + +*Syntax*: +---------------------------- +hide_edge_borders +---------------------------- + +*Example*: +---------------------- +hide_edge_borders vertical +---------------------- + === Arbitrary commands for specific windows (for_window) With the +for_window+ command, you can let i3 execute any command when it @@ -554,6 +615,22 @@ logfile first (see http://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 +workspace, but you don’t want to assign all instances of it permanently, you +can make use of i3’s startup-notification support (see <>) in your config +file in the following way: + +*Start iceweasel on workspace 3 (once)*: +------------------------------------------------------------------------------- +# Start iceweasel on workspace 3, then switch back to workspace 1 +# (Being a command-line utility, i3-msg does not support startup notifications, +# hence the exec --no-startup-id.) +# (Starting iceweasel with i3’s exec command is important in order to make i3 +# create a startup notification context, without which the iceweasel window(s) +# cannot be matched onto the workspace on which the command was started.) +exec --no-startup-id i3-msg 'workspace 3; exec iceweasel; workspace 1' +------------------------------------------------------------------------------- + === Automatically starting applications on i3 startup By using the +exec+ keyword outside a keybinding, you can configure @@ -691,11 +768,12 @@ the next section. === Focus follows mouse -If you have a setup where your mouse usually is in your way (like a touchpad -on your laptop which you do not want to disable completely), you might want -to disable 'focus follows mouse' and control focus only by using your keyboard. -The mouse will still be useful inside the currently active window (for example -to click on links in your browser window). +By default, window focus follows your mouse movements. However, if you have a +setup where your mouse usually is in your way (like a touchpad on your laptop +which you do not want to disable completely), you might want to disable 'focus +follows mouse' and control focus only by using your keyboard. The mouse will +still be useful inside the currently active window (for example to click on +links in your browser window). *Syntax*: ---------------------------- @@ -990,8 +1068,7 @@ xrandr --output --primary === Font -Specifies the font (again, X core font, not Xft, just like in i3) to be used in -the bar. +Specifies the font to be used in the bar. See <>. *Syntax*: --------------------- @@ -1002,6 +1079,7 @@ font -------------------------------------------------------------- bar { font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1 + font xft:DejaVu Sans Mono 10 } -------------------------------------------------------------- @@ -1170,13 +1248,15 @@ cursor for 60 seconds. === Splitting containers The split command makes the current window a split container. Split containers -can contain multiple windows. Every split container has an orientation, it is -either split horizontally (a new window gets placed to the right of the current -one) or vertically (a new window gets placed below the current one). +can contain multiple windows. Depending on the layout of the split container, +new windows get placed to the right of the current one (splith) or new windows +get placed below the current one (splitv). If you apply this command to a split container with the same orientation, nothing will happen. If you use a different orientation, the split container’s -orientation will be changed (if it does not have more than one window). +orientation will be changed (if it does not have more than one window). Use ++layout toggle split+ to change the layout of any split container from splitv +to splith or vice-versa. *Syntax*: --------------------------- @@ -1191,19 +1271,32 @@ bindsym mod+h split horizontal === Manipulating layout -Use +layout default+, +layout stacking+ or +layout tabbed+ to change the -current container layout to default, stacking or tabbed layout, respectively. +Use +layout toggle split+, +layout stacking+ or +layout tabbed+ to change the +current container layout to splith/splitv, stacking or tabbed layout, +respectively. To make the current window (!) fullscreen, use +fullscreen+, to make it floating (or tiling again) use +floating enable+ respectively +floating disable+ (or +floating toggle+): +*Syntax*: +-------------- +layout +layout toggle [split|all] +-------------- + *Examples*: -------------- bindsym mod+s layout stacking -bindsym mod+l layout default +bindsym mod+l layout toggle split bindsym mod+w layout tabbed +# Toggle between stacking/tabbed/split: +bindsym mod+x layout toggle + +# Toggle between stacking/tabbed/splith/splitv: +bindsym mod+x layout toggle all + # Toggle fullscreen bindsym mod+f fullscreen @@ -1293,22 +1386,28 @@ You can also switch to the next and previous workspace with the commands workspace 1, 3, 4 and 9 and you want to cycle through them with a single key combination. To restrict those to the current output, use +workspace next_on_output+ and +workspace prev_on_output+. Similarly, you can use +move -container to workspace next+ and +move container to workspace prev+ to move a -container to the next/previous workspace. +container to workspace next+, +move container to workspace prev+ to move a +container to the next/previous workspace and +move container to workspace current+ +(the last one makes sense only when used with criteria). + +See <> for how to move a container/workspace to a different +RandR output. [[back_and_forth]] To switch back to the previously focused workspace, use +workspace back_and_forth+. -To move a container to another xrandr output such as +LVDS1+ or +VGA1+, you can -use the +move container to output+ command followed by the name of the target -output. You may also use +left+, +right+, +up+, +down+ instead of the xrandr -output name to move to the next output in the specified direction. - -To move a whole workspace to another xrandr output such as +LVDS1+ or +VGA1+, -you can use the +move workspace to output+ command followed by the name of the -target output. You may also use +left+, +right+, +up+, +down+ instead of the -xrandr output name to move to the next output in the specified direction. +*Syntax*: +----------------------------------- +workspace +workspace back_and_forth +workspace +workspace number + +move [window|container] [to] workspace +move [window|container] [to] workspace number +move [window|container] [to] workspace +----------------------------------- *Examples*: ------------------------- @@ -1325,6 +1424,9 @@ bindsym mod+b workspace back_and_forth # move the whole workspace to the next output bindsym mod+x move workspace to output right + +# move firefox to current workspace +bindsym mod+F1 [class="Firefox"] move workspace current ------------------------- ==== Named workspaces @@ -1356,7 +1458,7 @@ to switch to the workspace which begins with number 1, regardless of which name it has. This is useful in case you are changing the workspace’s name dynamically. -=== Renaming workspaces +==== 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 @@ -1374,6 +1476,30 @@ i3-msg 'rename workspace 1 to "1: www"' i3-msg 'rename workspace "1: www" to "10: www"' ------------------------------------------------ +=== Moving containers/workspaces to RandR outputs + +[[move_to_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: + +*Syntax*: +-------------------------------------------------------- +move container to output <|> +move workspace to output <|> +-------------------------------------------------------- + +*Examples*: +-------------------------------------------------------- +# Move the current workspace to the next output +# (effectively toggles when you only have two outputs) +bindsym mod+x move workspace to output right + +# Put this window on the presentation output. +bindsym mod+x move container to output VGA1 +-------------------------------------------------------- + [[resizingconfig]] === Resizing containers/windows diff --git a/docs/debugging-release-version.html b/docs/debugging-release-version.html index f7ec1c5..d009361 100644 --- a/docs/debugging-release-version.html +++ b/docs/debugging-release-version.html @@ -4,7 +4,7 @@ - + i3: Debugging i3: How To (release version) diff --git a/docs/debugging.html b/docs/debugging.html index 2fc749b..af696cb 100644 --- a/docs/debugging.html +++ b/docs/debugging.html @@ -4,7 +4,7 @@ - + i3: Debugging i3: How To diff --git a/docs/hacking-howto.html b/docs/hacking-howto.html index afdca82..29405fc 100644 --- a/docs/hacking-howto.html +++ b/docs/hacking-howto.html @@ -4,7 +4,7 @@ - + i3: Hacking i3: How To @@ -152,7 +152,7 @@ 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.

 @@ -304,7 +304,7 @@ src/log.c

-Handles the setting of loglevels, contains the logging functions. +Contains the logging functions.

diff --git a/docs/index.html.mako b/docs/index.html.mako index 1608d64..bf80d27 100644 --- a/docs/index.html.mako +++ b/docs/index.html.mako @@ -3,7 +3,7 @@ %> <%inherit file="_templates/i3.mako" />
-

Documentation for i3 v4.2

+

Documentation for i3 v4.3

One of i3’s goals is good documentation. The documents which you will find diff --git a/docs/ipc.html b/docs/ipc.html index 5eb4122..4b20c01 100644 --- a/docs/ipc.html +++ b/docs/ipc.html @@ -4,7 +4,7 @@ - + i3: IPC interface (interprocess communication) @@ -31,7 +31,7 @@ window.onload = function(){asciidoc.footnotes(); asciidoc.toc(2);}

IPC interface (interprocess communication)

Michael Stapelberg
<michael@i3wm.org>
-February 2012 +August 2012
Table of Contents
@@ -148,6 +148,15 @@ GET_BAR_CONFIG (6) 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. +

+

So, a typical message could look like this:

@@ -246,6 +255,14 @@ BAR_CONFIG (6) Reply to the GET_BAR_CONFIG message.

+
+VERSION (7) +
+
+

+ Reply to the GET_VERSION message. +

+
@@ -372,7 +389,7 @@ default) or whether a JSON parse error occurred.

-

3.5. GET_OUTPUTS reply

+

3.5. OUTPUTS reply

The reply consists of a serialized list of outputs. Each output has the following properties:

@@ -482,7 +499,8 @@ layout (string)

- Can be either "default", "stacked", "tabbed", "dockarea" or "output". + Can be either "splith", "splitv", "stacked", "tabbed", "dockarea" or + "output". Other values might be possible in the future, should we add new layouts.

@@ -494,6 +512,8 @@ orientation (string)

Can be either "none" (for non-split containers), "horizontal" or "vertical". + THIS FIELD IS OBSOLETE. It is still present, but your code should not + use it. Instead, rely on the layout field.

@@ -541,6 +561,17 @@ geometry (map)

+window (integer) +
+
+

+ The X11 window ID of the actual client window inside this container. + This field is set to null for split containers or otherwise empty + containers. This ID corresponds to what xwininfo(1) and other + X11-related tools display (usually in hex). +

+
+
urgent (bool)
@@ -922,6 +953,60 @@ urgent_workspace_text/urgent_workspace_bar }
+
+

3.9. VERSION reply

+

The reply consists of a single JSON dictionary with the following keys:

+
+
+major (integer) +
+
+

+ The major version of i3, such as 4. +

+
+
+minor (integer) +
+
+

+ The minor version of i3, such as 2. Changes in the IPC interface (new + features) will only occur with new minor (or major) releases. However, + bugfixes might be introduced in patch releases, too. +

+
+
+patch (integer) +
+
+

+ The patch version of i3, such as 1 (when the complete version is + 4.2.1). For versions such as 4.2, patch will be set to 0. +

+
+
+human_readable (string) +
+
+

+ A human-readable version of i3 containing the precise git version, + build date and branch name. When you need to display the i3 version to + your users, use the human-readable version whenever possible (since + this is what i3 --version displays, too). +

+
+
+

Example:

+
+
+
{
+   "human_readable" : "4.2-169-gf80b877 (2012-08-05, branch \"next\")",
+   "minor" : 2,
+   "patch" : 0,
+   "major" : 4
+}
+
+
@@ -1047,17 +1132,25 @@ Perl

- http://search.cpan.org/search?query=AnyEvent::I3 + https://metacpan.org/module/AnyEvent::I3

Python
+
diff --git a/docs/testsuite.html b/docs/testsuite.html index 35acb27..1d61940 100644 --- a/docs/testsuite.html +++ b/docs/testsuite.html @@ -4,7 +4,7 @@ - + i3: i3 testsuite @@ -30,8 +30,8 @@ window.onload = function(){asciidoc.footnotes(); asciidoc.toc(2);}
-

2. Implementation

+

2. Relevant documentation

+
+

Apart from this document, you should also have a look at:

+
    +
  1. +

    +The "Modern Perl" book, which can be found at + http://onyxneon.com/books/modern_perl/modern_perl_a4.pdf +

    +
    2. +
  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 +

    +
    3. +
  3. +

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

    +
    4. +
+
+
+
+

3. Implementation

For several reasons, the i3 testsuite has been implemented in Perl:

    @@ -93,12 +121,18 @@ Perl is widely available and has a well-working package infrastructure. The author is familiar with Perl :).

    +
  1. +

    +It is a good idea to use a different language for the tests than the + implementation itself. +

    +

Please do not start programming language flamewars at this point.

-

2.1. Mechanisms

+

3.1. Mechanisms

-

2.1.1. Script: complete-run

+

3.1.1. Script: complete-run

The testcases are run by a script called complete-run.pl. It runs all testcases by default, but you can be more specific and let it only run one or more testcases. Also, it takes care of starting up a separate instance of i3 @@ -147,7 +181,7 @@ $ less latest/i3-log-for-04-floating.t

-

2.1.2. IPC interface

+

3.1.2. IPC interface

The testsuite makes extensive use of the IPC (Inter-Process Communication) 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 @@ -155,7 +189,7 @@ current state (layout tree).

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

-

2.1.3. X11::XCB

+

3.1.3. X11::XCB

In order to open new windows, change attributes, get events, etc., the testsuite uses X11::XCB, a new (and quite specific to i3 at the moment) Perl module which uses the XCB protocol description to generate Perl bindings to @@ -166,7 +200,7 @@ manager.

-

2.2. Filesystem structure

+

3.2. Filesystem structure

In the git root of i3, the testcases live in the folder testcases. This folder contains the complete-run.pl and Xdummy scripts and a base configuration file which will be used for the tests. The different testcases @@ -196,7 +230,7 @@ conventionally named subfolder t:

-

3. Anatomy of a testcase

+

4. Anatomy of a testcase

Learning by example is definitely a good strategy when you are wondering how to write a testcase. Let’s take t/11-goto.t as an easy example and go through it @@ -388,7 +422,7 @@ IPC anymore.

-

4. Appendix A: The i3 sync protocol

+

5. Appendix A: The i3 sync protocol

Consider the following situation: You open two windows in your testcase, then you use focus left and want to verify that the X11 focus has been updated @@ -460,7 +494,7 @@ importantly, X11).

Figure 2. Diagram of the i3 sync solution
-

4.1. Implementation details

+

5.1. Implementation details

The client which wants to sync with i3 initiates the protocol by sending a ClientMessage to the X11 root window:

@@ -492,7 +526,7 @@ the same one when getting the reply.

-

5. Appendix B: Socket activation

+

6. Appendix B: Socket activation

Socket activation is a mechanism which was made popular by systemd, an init replacement. It basically describes creating a listening socket before starting @@ -501,7 +535,7 @@ the socket is made, hence the term socket activation.

The interesting part of this (in the i3 context) is that you can very precisely detect when the program is ready (finished its initialization).

-

5.1. Preparing the listening socket

+

6.1. Preparing the listening socket

complete-run.pl will create a listening UNIX socket which it will then pass to i3. This socket will be used by i3 as an additional IPC socket, just like the one it will create on its own. Passing the socket happens implicitly @@ -546,7 +580,7 @@ if ($pid == 0) {

-

5.2. Waiting for a reply

+

6.2. Waiting for a reply

In the parent process, we want to know when i3 is ready to answer our IPC requests and handle our windows. Therefore, after forking, we immediately close the listening socket (i3 will handle this side of the socket) and connect to it @@ -563,7 +597,7 @@ completed successfully by the time the event loop is entered, we can now assume that i3 is ready.

-

5.3. Timing and conclusion

+

6.3. Timing and conclusion

A beautiful feature of this mechanism is that it does not depend on timing. It does not matter when the child process gets CPU time or when the parent process gets CPU time. On heavily loaded machines (or machines with multiple CPUs, diff --git a/docs/userguide.html b/docs/userguide.html index a0cdea9..3f96d9e 100644 --- a/docs/userguide.html +++ b/docs/userguide.html @@ -4,7 +4,7 @@ - + i3: i3 User’s Guide @@ -30,8 +30,8 @@ window.onload = function(){asciidoc.footnotes(); asciidoc.toc(2);}

2.2. Changing the container layout

A split container can have one of the following layouts:

-default +splith/splitv

Windows are sized so that every window gets an equal amount of space in the -container. +container. splith distributes the windows horizontally (windows are right next +to each other), splitv distributes them vertically (windows are on top of each +other).

@@ -135,8 +137,8 @@ a single line which is vertically split.

-

To switch modes, press mod+e for default, mod+s for stacking and -mod+w for tabbed.

+

To switch modes, press mod+e for splith/splitv (it toggles), mod+s for +stacking and mod+w for tabbed.

Container modes

@@ -254,23 +256,24 @@ like this:

3.2. Orientation and Split Containers

It is only natural to use so-called Split Containers in order to build a layout when using a tree as data structure. In i3, every Container has an -orientation (horizontal, vertical or unspecified). So, in our example with the -workspace, the default orientation of the workspace Container is horizontal -(most monitors are widescreen nowadays). If you change the orientation to -vertical (mod+v in the default config) and then open two terminals, i3 will -configure your windows like this:

+orientation (horizontal, vertical or unspecified) and the orientation depends +on the layout the container is in (vertical for splitv and stacking, horizontal +for splith and tabbed). So, in our example with the workspace, the default +layout of the workspace Container is splith (most monitors are widescreen +nowadays). If you change the layout to splitv (mod+l in the default config) +and then open two terminals, i3 will configure your windows like this:

shot2
Figure 2. Vertical Workspace Orientation
-

An interesting new feature of the tree branch is the ability to split anything: -Let’s assume you have two terminals on a workspace (with horizontal -orientation), focus is on the right terminal. Now you want to open another -terminal window below the current one. If you would just open a new terminal -window, it would show up to the right due to the horizontal workspace -orientation. Instead, press mod+v to create a Vertical Split Container (to +

An interesting new feature of i3 since version 4 is the ability to split anything: +Let’s assume you have two terminals on a workspace (with splith layout, that is +horizontal orientation), focus is on the right terminal. Now you want to open +another terminal window below the current one. If you would just open a new +terminal window, it would show up to the right due to the splith layout. +Instead, press mod+v to split the container with the splitv layout (to open a Horizontal Split Container, use mod+h). Now you can open a new terminal and it will open below the current one:

@@ -305,6 +308,22 @@ windows will be opened to the right of the Vertical Split Container:

Figure 4. Focus parent, then open new terminal
+
+

3.4. Implicit containers

+

In some cases, i3 needs to implicitly create a container to fulfill your +command.

+

One example is the following scenario: You start i3 with a single monitor and a +single workspace on which you open three terminal windows. All these terminal +windows are directly attached to one node inside i3’s layout tree, the +workspace node. By default, the workspace node’s orientation is horizontal.

+

Now you move one of these terminals down (mod+k by default). The workspace +node’s orientation will be changed to vertical. The terminal window you moved +down is directly attached to the workspace and appears on the bottom of the +screen. A new (horizontal) container was created to accomodate the other two +terminal windows. You will notice this when switching to tabbed mode (for +example). You would end up having one tab called "another container" and the +other one being the terminal window you moved down.

+
@@ -341,21 +360,29 @@ a # and can only be used at the beginning of a line:

-

4.2. Fonts

-

i3 uses X core fonts (not Xft) for rendering window titles. You can use -xfontsel(1) to generate such a font description. To see special characters -(Unicode), you need to use a font which supports the ISO-10646 encoding.

+

4.2. Fonts

+

i3 has support for both X core fonts and FreeType fonts (through Pango) to +render window titles.

+

To generate an X core font description, you can use xfontsel(1). To see +special characters (Unicode), you need to use a font which supports the +ISO-10646 encoding.

+

A FreeType font description is composed by a font family, a style, a weight, +a variant, a stretch and a size. +FreeType fonts support right-to-left rendering and contain often more +Unicode glyphs than X core fonts.

If i3 cannot open the configured font, it will output an error in the logfile and fall back to a working font.

Syntax:

-
font <X core font description>
+
font <X core font description>
+font xft:<a FreeType font description>

Examples:

-
font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1
+
font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1
+font xft:DejaVu Sans Mono 10
@@ -385,11 +412,15 @@ Keycodes do not need to have a symbol assigned (handy for custom vendor your bindings in the same physical location on the keyboard, use keycodes. If you don’t switch layouts, and want a clean and simple config file, use keysyms.

+

Some tools (such as import or xdotool) might be unable to run upon a +KeyPress event, because the keyboard/pointer is still grabbed. For these +situations, the --release flag can be used, which will execute the command +after the keys have been released.

Syntax:

-
bindsym [Modifiers+]keysym command
-bindcode [Modifiers+]keycode command
+
bindsym [--release] [Modifiers+]keysym command
+bindcode [--release] [Modifiers+]keycode command

Examples:

@@ -401,7 +432,13 @@ bindsym mod+f fullscreen bindsym mod+Shift+r restart # Notebook-specific hotkeys -bindcode 214 exec /home/michael/toggle_beamer.sh +bindcode 214 exec --no-startup-id /home/michael/toggle_beamer.sh + +# Simulate ctrl+v upon pressing $mod+x +bindsym --release $mod+x exec --no-startup-id xdotool key --clearmodifiers ctrl+v + +# Take a screenshot upon pressing $mod+x (select an area) +bindsym --release $mod+x exec --no-startup-id import /tmp/latest-screenshot.png

Available Modifiers:

@@ -506,7 +543,8 @@ start.

4.8. Border style for new windows

-

This option determines which border style new windows will have.

+

This option determines which border style new windows will have. The default is +"normal".

Syntax:

@@ -519,7 +557,23 @@ start.

-

4.9. Arbitrary commands for specific windows (for_window)

+

4.9. Hiding vertical borders

+

You can hide vertical borders adjacent to the screen edges using +hide_edge_borders. This is useful if you are using scrollbars, or do not want +to waste even two pixels in displayspace. Default is none.

+

Syntax:

+
+
+
hide_edge_borders <none|vertical|horizontal|both>
+
+

Example:

+
+
+
hide_edge_borders vertical
+
+
+
+

4.10. Arbitrary commands for specific windows (for_window)

With the for_window command, you can let i3 execute any command when it encounters a specific window. This can be used to set windows to floating or to change their border style, for example.

@@ -545,7 +599,7 @@ for_window [title="x200: ~/work"] floating enable

The valid criteria are the same as those for commands, see [command_criteria].

-

4.10. Variables

+

4.11. Variables

As you learned in the section about keyboard bindings, you will have to configure lots of bindings containing modifier keys. If you want to save yourself some typing and be able to change the modifier you use later, @@ -568,7 +622,7 @@ configuration file and run it before starting i3 (for example in your ~/.xsession file).

-

4.11. Automatically putting clients on specific workspaces

+

4.12. Automatically putting clients on specific workspaces

To automatically make a specific window show up on a specific workspace, you can use an assignment. You can match windows by using any criteria, see [command_criteria]. It is recommended that you match on window classes @@ -617,9 +671,24 @@ second part is the class ("URxvt" in this example).

logfile first (see http://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 +workspace, but you don’t want to assign all instances of it permanently, you +can make use of i3’s startup-notification support (see [exec]) in your config +file in the following way:

+

Start iceweasel on workspace 3 (once):

+
+
+
# Start iceweasel on workspace 3, then switch back to workspace 1
+# (Being a command-line utility, i3-msg does not support startup notifications,
+#  hence the exec --no-startup-id.)
+# (Starting iceweasel with i3’s exec command is important in order to make i3
+#  create a startup notification context, without which the iceweasel window(s)
+#  cannot be matched onto the workspace on which the command was started.)
+exec --no-startup-id i3-msg 'workspace 3; exec iceweasel; workspace 1'
+
-

4.12. Automatically starting applications on i3 startup

+

4.13. Automatically starting applications on i3 startup

By using the exec keyword outside a keybinding, you can configure which commands will be performed by i3 on initial startup. exec commands will not run when restarting i3, if you need a command to run @@ -643,7 +712,7 @@ exec --no-startup-id urxvt

The flag --no-startup-id is explained in [exec].

-

4.13. Automatically putting workspaces on specific screens

+

4.14. Automatically putting workspaces on specific screens

If you assign clients to workspaces, it might be handy to put the workspaces on specific screens. Also, the assignment of workspaces to screens will determine which workspace i3 uses for a new screen when adding screens @@ -667,7 +736,7 @@ workspace "2: vim" output VGA1

-

4.14. Changing colors

+

4.15. Changing colors

You can change all colors which i3 uses to draw the window decorations.

Syntax:

@@ -743,7 +812,7 @@ single windows within a split container, which are otherwise indistinguishable from single windows outside of a split container.

-

4.15. Interprocess communication

+

4.16. Interprocess communication

i3 uses unix sockets to provide an IPC interface. This allows third-party programs to get information from i3, such as the current workspaces (to display a workspace bar), and to control i3.

@@ -765,12 +834,13 @@ user can create that directory.

the next section.

-

4.16. Focus follows mouse

-

If you have a setup where your mouse usually is in your way (like a touchpad -on your laptop which you do not want to disable completely), you might want -to disable focus follows mouse and control focus only by using your keyboard. -The mouse will still be useful inside the currently active window (for example -to click on links in your browser window).

+

4.17. Focus follows mouse

+

By default, window focus follows your mouse movements. However, if you have a +setup where your mouse usually is in your way (like a touchpad on your laptop +which you do not want to disable completely), you might want to disable focus +follows mouse and control focus only by using your keyboard. The mouse will +still be useful inside the currently active window (for example to click on +links in your browser window).

Syntax:

@@ -783,7 +853,7 @@ to click on links in your browser window).

-

4.17. Popups during fullscreen mode

+

4.18. Popups during fullscreen mode

When you are in fullscreen mode, some applications still open popup windows (take Xpdf for example). This is because these applications may not be aware that they are in fullscreen mode (they do not check the corresponding hint). @@ -814,7 +884,7 @@ Leave fullscreen mode. This is the default.

-

4.18. Focus wrapping

+

4.19. Focus wrapping

When being in a tabbed or stacked container, the first container will be focused when you use focus down on the last container — the focus wraps. If however there is another stacked/tabbed container in that direction, focus will @@ -836,7 +906,7 @@ will always wrap.

-

4.19. Forcing Xinerama

+

4.20. Forcing Xinerama

As explained in-depth in http://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 @@ -859,7 +929,7 @@ that’s it).

Xinerama, instead they are counted up, starting at 0: xinerama-0, xinerama-1, …

-

4.20. Automatic back-and-forth when switching to the current workspace

+

4.21. Automatic back-and-forth when switching to the current workspace

This configuration directive enables automatic workspace back_and_forth (see [back_and_forth]) when switching to the workspace that is currently focused.

For instance: Assume you are on workspace "1: www" and switch to "2: IM" using @@ -1073,8 +1143,7 @@ bar {

5.7. Font

-

Specifies the font (again, X core font, not Xft, just like in i3) to be used in -the bar.

+

Specifies the font to be used in the bar. See [fonts].

Syntax:

@@ -1085,6 +1154,7 @@ the bar.

bar {
     font -misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1
+    font xft:DejaVu Sans Mono 10
 }
@@ -1331,12 +1401,14 @@ cursor for 60 seconds.

6.2. Splitting containers

The split command makes the current window a split container. Split containers -can contain multiple windows. Every split container has an orientation, it is -either split horizontally (a new window gets placed to the right of the current -one) or vertically (a new window gets placed below the current one).

+can contain multiple windows. Depending on the layout of the split container, +new windows get placed to the right of the current one (splith) or new windows +get placed below the current one (splitv).

If you apply this command to a split container with the same orientation, nothing will happen. If you use a different orientation, the split container’s -orientation will be changed (if it does not have more than one window).

+orientation will be changed (if it does not have more than one window). Use +layout toggle split to change the layout of any split container from splitv +to splith or vice-versa.

Syntax:

@@ -1351,18 +1423,31 @@ bindsym mod+h split horizontal

6.3. Manipulating layout

-

Use layout default, layout stacking or layout tabbed to change the -current container layout to default, stacking or tabbed layout, respectively.

+

Use layout toggle split, layout stacking or layout tabbed to change the +current container layout to splith/splitv, stacking or tabbed layout, +respectively.

To make the current window (!) fullscreen, use fullscreen, to make it floating (or tiling again) use floating enable respectively floating disable (or floating toggle):

+

Syntax:

+
+
+
layout <tabbed|stacking>
+layout toggle [split|all]
+

Examples:

bindsym mod+s layout stacking
-bindsym mod+l layout default
+bindsym mod+l layout toggle split
 bindsym mod+w layout tabbed
 
+# Toggle between stacking/tabbed/split:
+bindsym mod+x layout toggle
+
+# Toggle between stacking/tabbed/splith/splitv:
+bindsym mod+x layout toggle all
+
 # Toggle fullscreen
 bindsym mod+f fullscreen
 
@@ -1485,18 +1570,25 @@ number or name of the workspace. To move containers to specific workspaces, use
 workspace 1, 3, 4 and 9 and you want to cycle through them with a single key
 combination. To restrict those to the current output, use workspace
 next_on_output and workspace prev_on_output. Similarly, you can use move
-container to workspace next and move container to workspace prev to move a
-container to the next/previous workspace.
+container to workspace next, move container to workspace prev to move a +container to the next/previous workspace and move container to workspace current +(the last one makes sense only when used with criteria).

+

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

To switch back to the previously focused workspace, use workspace back_and_forth.

-

To move a container to another xrandr output such as LVDS1 or VGA1, you can -use the move container to output command followed by the name of the target -output. You may also use left, right, up, down instead of the xrandr -output name to move to the next output in the specified direction.

-

To move a whole workspace to another xrandr output such as LVDS1 or VGA1, -you can use the move workspace to output command followed by the name of the -target output. You may also use left, right, up, down instead of the -xrandr output name to move to the next output in the specified direction.

+

Syntax:

+
+
+
workspace <next|prev|next_on_output|prev_on_output>
+workspace back_and_forth
+workspace <name>
+workspace number <number>
+
+move [window|container] [to] workspace <name>
+move [window|container] [to] workspace number <number>
+move [window|container] [to] workspace <prev|next|current>
+

Examples:

@@ -1512,7 +1604,10 @@ bindsym mod+Shift+2 move container to workspace 2 bindsym mod+b workspace back_and_forth # move the whole workspace to the next output -bindsym mod+x move workspace to output right +bindsym mod+x move workspace to output right + +# move firefox to current workspace +bindsym mod+F1 [class="Firefox"] move workspace current

6.5.1. Named workspaces

@@ -1541,9 +1636,8 @@ to switch to the workspace which begins with number 1, regardless of which name it has. This is useful in case you are changing the workspace’s name dynamically.

-
-
-

6.6. Renaming workspaces

+
+

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

@@ -1560,6 +1654,29 @@ i3-msg 'rename workspace 1 to "1: www"' i3-msg 'rename workspace "1: www" to "10: www"'
+ +
+

6.6. 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:

+

Syntax:

+
+
+
move container to output <<left|right|down|up>|<output>>
+move workspace to output <<left|right|down|up>|<output>>
+
+

Examples:

+
+
+
# Move the current workspace to the next output
+# (effectively toggles when you only have two outputs)
+bindsym mod+x move workspace to output right
+
+# Put this window on the presentation output.
+bindsym mod+x move container to output VGA1
+
+

6.7. Resizing containers/windows

If you want to resize containers/windows using your keyboard, you can use the diff --git a/docs/wsbar.html b/docs/wsbar.html index 7a3b822..81f2c22 100644 --- a/docs/wsbar.html +++ b/docs/wsbar.html @@ -4,7 +4,7 @@ - + i3: External workspace bars -- 2.39.2

To get an impression of how different layouts are represented, just play around and look at the data structures — they are exposed as a JSON hash. See -http://i3wm.org/docs/ipc.html#_get_tree_reply for documentation on that and an +http://i3wm.org/docs/ipc.html#_tree_reply for documentation on that and an example.