From 8924ec1339061840e02c918d36c86dd179a86aac Mon Sep 17 00:00:00 2001 From: Michael Stapelberg Date: Sat, 10 Mar 2018 18:30:15 +0100 Subject: [PATCH] update docs for 4.15 --- _docs/debugging | 4 +- _docs/i3bar-protocol | 14 ++- _docs/ipc | 48 +++++++++- _docs/testsuite | 6 +- _docs/userguide | 124 +++++++++++++++++-------- docs/debugging.html | 4 +- docs/i3bar-protocol.html | 26 +++++- docs/ipc.html | 70 +++++++++++++- docs/testsuite.html | 6 +- docs/userguide.html | 194 ++++++++++++++++++++++++--------------- 10 files changed, 361 insertions(+), 135 deletions(-) diff --git a/_docs/debugging b/_docs/debugging index 8c6b2b7..9734b21 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.1 +== Verify you are using i3 ≥ 4.15 Only the latest major version of i3 is supported. To verify which version you are running, use: @@ -153,7 +153,7 @@ When sending bug reports, please attach the *whole* log file. Even if you think 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 +When debugging with us in IRC, be prepared to use a so-called nopaste service 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/i3bar-protocol b/_docs/i3bar-protocol index b8c2b5a..cf86531 100644 --- a/_docs/i3bar-protocol +++ b/_docs/i3bar-protocol @@ -177,7 +177,8 @@ separator_block_width:: markup:: A string that indicates how the text of the block should be parsed. Set to +"pango"+ to use https://developer.gnome.org/pango/stable/PangoMarkupFormat.html[Pango markup]. - Set to +"none"+ to not use any markup (default). + Set to +"none"+ to not use any markup (default). Pango markup only works + if you use a pango font. If you want to put in your own entries into a block, prefix the key with an underscore (_). i3bar will ignore all keys it doesn’t understand, and prefixing @@ -236,6 +237,11 @@ x, y:: X11 root window coordinates where the click occurred button:: X11 button ID (for example 1 to 3 for left/middle/right mouse button) +relative_x, relative_y:: + Coordinates where the click occurred, with respect to the top left corner + of the block +width, height:: + Width and height (in px) of the block *Example*: ------------------------------------------ @@ -244,6 +250,10 @@ button:: "instance": "eth0", "button": 1, "x": 1320, - "y": 1400 + "y": 1400, + "relative_x": 12, + "relative_y": 8, + "width": 50, + "height": 22 } ------------------------------------------ diff --git a/_docs/ipc b/_docs/ipc index 2a6112b..8b767ad 100644 --- a/_docs/ipc +++ b/_docs/ipc @@ -64,6 +64,7 @@ to do that). | 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. +| 10 | +SEND_TICK+ | <<_tick_reply,TICK>> | Sends a tick event with the specified payload. |====================================================== So, a typical message could look like this: @@ -126,6 +127,8 @@ BINDING_MODES (8):: Reply to the GET_BINDING_MODES message. GET_CONFIG (9):: Reply to the GET_CONFIG message. +TICK (10):: + Reply to the SEND_TICK message. [[_command_reply]] === COMMAND reply @@ -637,6 +640,19 @@ which is a string containing the config file as loaded by i3 most recently. { "config": "font pango:monospace 8\nbindsym Mod4+q exit\n" } ------------------- +[[_tick_reply]] +=== TICK reply + +The reply is a map containing the "success" member. After the reply was +received, the tick event has been written to all IPC connections which subscribe +to tick events. UNIX sockets are usually buffered, but you can be certain that +once you receive the tick event you just triggered, you must have received all +events generated prior to the +SEND_TICK+ message (happened-before relation). + +*Example:* +------------------- +{ "success": true } +------------------- == Events @@ -694,6 +710,10 @@ binding (5):: mouse shutdown (6):: Sent when the ipc shuts down because of a restart or exit by user command +tick (7):: + Sent when the ipc client subscribes to the tick event (with +"first": + true+) or when any ipc client sends a SEND_TICK message (with +"first": + false+). *Example:* -------------------------------------------------------------------- @@ -866,6 +886,27 @@ because of a user action such as a +restart+ or +exit+ command. The +change } --------------------------- +=== tick event + +This event is triggered by a subscription to tick events or by a +SEND_TICK+ +message. + +*Example (upon subscription):* +-------------------------------------------------------------------------------- +{ + "first": true, + "payload": "" +} +-------------------------------------------------------------------------------- + +*Example (upon +SEND_TICK+ with a payload of +arbitrary string+):* +-------------------------------------------------------------------------------- +{ + "first": false, + "payload": "arbitrary string" +} +-------------------------------------------------------------------------------- + == See also (existing libraries) [[libraries]] @@ -879,10 +920,9 @@ C:: * https://github.com/acrisci/i3ipc-glib C++:: * https://github.com/drmgc/i3ipcpp -Crystal:: - * https://github.com/woodruffw/i3.cr Go:: * https://github.com/mdirkse/i3ipc-go + * https://github.com/i3/go-i3 JavaScript:: * https://github.com/acrisci/i3ipc-gjs Lua:: @@ -891,7 +931,6 @@ Perl:: * https://metacpan.org/module/AnyEvent::I3 Python:: * https://github.com/acrisci/i3ipc-python - * https://github.com/Ceryn/i3msg-python * https://github.com/whitelynx/i3ipc (not maintained) * https://github.com/ziberna/i3-py (not maintained) Ruby:: @@ -961,3 +1000,6 @@ detect the byte order i3 is using: 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. + +Find an example implementation of this technique in +https://github.com/i3/go-i3/blob/master/byteorder.go diff --git a/_docs/testsuite b/_docs/testsuite index bf85cb1..b535e7c 100644 --- a/_docs/testsuite +++ b/_docs/testsuite @@ -113,10 +113,8 @@ containing the appropriate i3 logfile for each testcase. The latest folder can always be found under the symlink +latest/+. Unless told differently, it will run the tests on a separate X server instance (using Xephyr). -Xephyr will open a window where you can inspect the running test. You can run -the tests without an X session with Xvfb, such as with +xvfb-run -./complete-run+. This will also speed up the tests significantly especially on -machines without a powerful video card. +Xephyr will open a window where you can inspect the running test. By default, +tests are run under Xvfb. .Example invocation of +complete-run.pl+ --------------------------------------- diff --git a/_docs/userguide b/_docs/userguide index 67a00b1..ba314af 100644 --- a/_docs/userguide +++ b/_docs/userguide @@ -1,7 +1,6 @@ i3 User’s Guide =============== Michael Stapelberg -March 2013 This document contains all the information you need to configure and use the i3 window manager. If it does not, please check https://www.reddit.com/r/i3wm/ @@ -11,7 +10,7 @@ mailing list. == Default keybindings For the "too long; didn’t read" people, here is an overview of the default -keybindings (click to see the full size image): +keybindings (click to see the full-size image): *Keys to use with $mod (Alt):* @@ -35,7 +34,8 @@ above, just decline i3-config-wizard’s offer and base your config on Throughout this guide, the keyword +$mod+ will be used to refer to the configured modifier. This is the Alt key (+Mod1+) by default, with the Windows -key (+Mod4+) being a popular alternative. +key (+Mod4+) being a popular alternative that largely prevents conflicts with +application-defined shortcuts. === Opening terminals and moving around @@ -196,7 +196,7 @@ out to be complicated to use (snapping), understand and implement. === The tree consists of Containers -The building blocks of our tree are so called +Containers+. A +Container+ can +The building blocks of our tree are so-called +Containers+. A +Container+ can host a window (meaning an X11 window, one that you can actually see and use, like a browser). Alternatively, it could contain one or more +Containers+. A simple example is the workspace: When you start i3 with a single monitor, a @@ -244,7 +244,7 @@ vertically split terminals on the right, focus is on the bottom right one. When you open a new terminal, it will open below the current one. So, how can you open a new terminal window to the *right* of the current one? -The solution is to use +focus parent+ (+$mod+a+ by default), which will focus the +Parent Container+ of +The solution is to use +focus parent+, which will focus the +Parent Container+ of the current +Container+. In this case, you would focus the +Vertical Split Container+ which is *inside* the horizontally oriented workspace. Thus, now new windows will be opened to the right of the +Vertical Split Container+: @@ -509,7 +509,7 @@ mode "$mode_launcher" { === The floating modifier To move floating windows with your mouse, you can either grab their titlebar -or configure the so called floating modifier which you can then press and +or configure the so-called floating modifier which you can then press and click anywhere in the window itself to move it. The most common setup is to use the same key you use for managing windows (Mod1 for example). Then you can press Mod1, click into a window using your left mouse button, and drag @@ -585,23 +585,26 @@ workspace_layout default|stacking|tabbed workspace_layout tabbed --------------------- -=== Border style for new windows +=== Default border style for new windows This option determines which border style new windows will have. The default is -+normal+. Note that new_float applies only to windows which are starting out as ++normal+. Note that default_floating_border applies only to windows which are starting out as floating windows, e.g., dialog windows, but not windows that are floated later on. *Syntax*: --------------------------------------------- -new_window normal|none|pixel -new_window normal|pixel -new_float normal|none|pixel -new_float normal|pixel +default_border normal|none|pixel +default_border normal|pixel +default_floating_border normal|none|pixel +default_floating_border normal|pixel --------------------------------------------- +Please note that +new_window+ and +new_float+ have been deprecated in favor of the above options +and will be removed in a future release. We strongly recommend using the new options instead. + *Example*: --------------------- -new_window pixel +default_border pixel --------------------- The "normal" and "pixel" border styles support an optional border width in @@ -609,11 +612,11 @@ pixels: *Example*: --------------------- -# The same as new_window none -new_window pixel 0 +# The same as default_border none +default_border pixel 0 # A 3 px border -new_window pixel 3 +default_border pixel 3 --------------------- @@ -760,13 +763,18 @@ title change. As i3 will get the title as soon as the application maps the window (mapping means actually displaying it on the screen), you’d need to have to match on 'Firefox' in this case. +You can also assign a window to show up on a specific output. You can use RandR +names such as +VGA1+ or names relative to the output with the currently focused +workspace such as +left+ and +down+. + Assignments are processed by i3 in the order in which they appear in the config file. The first one which matches the window wins and later assignments are not considered. *Syntax*: ------------------------------------------------------------ -assign [→] [workspace] +assign [→] [workspace] [number] +assign [→] output left|right|up|down|primary| ------------------------------------------------------------ *Examples*: @@ -783,11 +791,28 @@ assign [class="^URxvt$"] → 2 # Assignment to a named workspace assign [class="^URxvt$"] → work +# Assign to the workspace with number 2, regardless of name +assign [class="^URxvt$"] → number 2 + +# You can also specify a number + name. If the workspace with number 2 exists, assign will skip the text part. +assign [class="^URxvt$"] → number "2: work" + # Start urxvt -name irssi assign [class="^URxvt$" instance="^irssi$"] → 3 + +# Assign urxvt to the output right of the current one +assign [class="^URxvt$"] → output right + +# Assign urxvt to the primary output +assign [class="^URxvt$"] → output primary ---------------------- -Note that the arrow is not required, it just looks good :-). If you decide to +Note that you might not have a primary output configured yet. To do so, run: +------------------------- +xrandr --output --primary +------------------------- + +Also, the arrow is not required, it just looks good :-). If you decide to use it, it has to be a UTF-8 encoded arrow, not `->` or something like that. To get the class and instance, you can use +xprop+. After clicking on the @@ -1033,26 +1058,39 @@ popup_during_fullscreen smart === 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 -be set on that container. This is the default behavior so you can navigate to -all your windows without having to use +focus parent+. +By default, when in a container with several windows or child containers, the +opposite window will be focused when trying to move the focus over the edge of +a container (and there are no other containers in that direction) -- the focus +wraps. + +If desired, you can disable this behavior by setting the +focus_wrapping+ +configuration directive to the value +no+. + +When enabled, focus wrapping does not occur by default if there is another +window or container in the specified direction, and focus will instead be set +on that window or container. This is the default behavior so you can navigate +to all your windows without having to use +focus parent+. If you want the focus to *always* wrap and you are aware of using +focus -parent+ to switch to different containers, you can use the -+force_focus_wrapping+ configuration directive. After enabling it, the focus -will always wrap. +parent+ to switch to different containers, you can instead set +focus_wrapping+ +to the value +force+. *Syntax*: --------------------------- -force_focus_wrapping yes|no ---------------------------- +focus_wrapping yes|no|force -*Example*: ------------------------- +# Legacy syntax, equivalent to "focus_wrapping force" force_focus_wrapping yes ------------------------- +--------------------------- + +*Examples*: +----------------- +# Disable focus wrapping +focus_wrapping no + +# Force focus wrapping +focus_wrapping force +----------------- === Forcing Xinerama @@ -1341,7 +1379,7 @@ and will be removed in a future release. We strongly recommend using the more ge *Syntax*: ---------------------------- -bindsym button +bindsym [--release] button ---------------------------- *Example*: @@ -1349,6 +1387,8 @@ bindsym button bar { # disable clicking on workspace buttons bindsym button1 nop + # Take a screenshot by right clicking on the bar + bindsym --release button3 exec --no-startup-id import /tmp/latest-screenshot.png # execute custom script when scrolling downwards bindsym button5 exec ~/.i3/scripts/custom_wheel_down } @@ -1913,6 +1953,9 @@ bindsym $mod+t floating toggle To change focus, you can use the +focus+ command. The following options are available: +:: + Sets focus to the container that matches the specified criteria. + See <>. left|right|up|down:: Sets focus to the nearest container in the given direction. parent:: @@ -1932,6 +1975,7 @@ output:: *Syntax*: ---------------------------------------------- + focus focus left|right|down|up focus parent|child|floating|tiling|mode_toggle focus output left|right|up|down|primary| @@ -1939,6 +1983,9 @@ focus output left|right|up|down|primary| *Examples*: ------------------------------------------------- +# Focus firefox +bindsym $mod+F1 [class="Firefox"] focus + # Focus container on the left, bottom, top, right bindsym $mod+j focus left bindsym $mod+k focus down @@ -2266,7 +2313,7 @@ If you want to resize containers/windows using your keyboard, you can use the *Syntax*: ------------------------------------------------------- resize grow|shrink [ px [or ppt]] -resize set [px] [px] +resize set [px | ppt] [px | ppt] ------------------------------------------------------- Direction can either be one of +up+, +down+, +left+ or +right+. Or you can be @@ -2275,8 +2322,11 @@ space from all the other containers. The optional pixel argument specifies by how many pixels a *floating container* should be grown or shrunk (the default is 10 pixels). The ppt argument means percentage points and specifies by how many percentage points a *tiling container* should be grown or shrunk (the -default is 10 percentage points). Note that +resize set+ will only work for -floating containers. +default is 10 percentage points). + +Notes about +resize set+: a value of 0 for or means "do +not resize in this direction", and resizing a tiling container by +px+ is not +implemented. It is recommended to define bindings for resizing in a dedicated binding mode. See <> and the example in the i3 @@ -2362,10 +2412,10 @@ TODO: make i3-input replace %s *Examples*: --------------------------------------- # Read 1 character and mark the current window with this character -bindsym $mod+m exec i3-input -p 'mark ' -l 1 -P 'Mark: ' +bindsym $mod+m exec i3-input -F 'mark %s' -l 1 -P 'Mark: ' # Read 1 character and go to the window with the character -bindsym $mod+g exec i3-input -p 'goto ' -l 1 -P 'Goto: ' +bindsym $mod+g exec i3-input -F '[con_mark="%s"] focus' -l 1 -P 'Goto: ' --------------------------------------- Alternatively, if you do not want to mess with +i3-input+, you could create diff --git a/docs/debugging.html b/docs/debugging.html index a98a417..da9dca0 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

+

1. Verify you are using i3 ≥ 4.15

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

@@ -221,7 +221,7 @@ starting at 0.

When sending bug reports, please attach the whole log file. Even if you think 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 +

When debugging with us in IRC, be prepared to use a so-called nopaste service 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/i3bar-protocol.html b/docs/i3bar-protocol.html index 4955b89..e84e177 100644 --- a/docs/i3bar-protocol.html +++ b/docs/i3bar-protocol.html @@ -322,7 +322,8 @@ markup

A string that indicates how the text of the block should be parsed. Set to "pango" to use Pango markup. - Set to "none" to not use any markup (default). + Set to "none" to not use any markup (default). Pango markup only works + if you use a pango font.

@@ -405,6 +406,23 @@ button X11 button ID (for example 1 to 3 for left/middle/right mouse button)

+
+relative_x, relative_y +
+
+

+ Coordinates where the click occurred, with respect to the top left corner + of the block +

+
+
+width, height +
+
+

+ Width and height (in px) of the block +

+

Example:

@@ -414,7 +432,11 @@ button "instance": "eth0", "button": 1, "x": 1320, - "y": 1400 + "y": 1400, + "relative_x": 12, + "relative_y": 8, + "width": 50, + "height": 22 }
diff --git a/docs/ipc.html b/docs/ipc.html index 34a55ea..350483e 100644 --- a/docs/ipc.html +++ b/docs/ipc.html @@ -171,6 +171,12 @@ cellspacing="0" cellpadding="4">

CONFIG

Returns the last loaded i3 config.

+ +

10

+

SEND_TICK

+

TICK

+

Sends a tick event with the specified payload.

+ @@ -295,6 +301,14 @@ GET_CONFIG (9) Reply to the GET_CONFIG message.

+
+TICK (10) +
+
+

+ Reply to the SEND_TICK message. +

+
@@ -1186,6 +1200,19 @@ which is a string containing the config file as loaded by i3 most recently.

< 
{ "config": "font pango:monospace 8\nbindsym Mod4+q exit\n" }
+
+

3.12. TICK reply

+

The reply is a map containing the "success" member. After the reply was +received, the tick event has been written to all IPC connections which subscribe +to tick events. UNIX sockets are usually buffered, but you can be certain that +once you receive the tick event you just triggered, you must have received all +events generated prior to the SEND_TICK message (happened-before relation).

+

Example:

+
+
+
{ "success": true }
+
+
@@ -1282,6 +1309,16 @@ shutdown (6) Sent when the ipc shuts down because of a restart or exit by user command

+
+tick (7) +
+
+

+ Sent when the ipc client subscribes to the tick event (with "first": + true) or when any ipc client sends a SEND_TICK message (with "first": + false). +

+

Example:

@@ -1520,6 +1557,27 @@ because of a user action such as a restart or exit command. Th }
+
+

4.10. tick event

+

This event is triggered by a subscription to tick events or by a SEND_TICK +message.

+

Example (upon subscription):

+
+
+
{
+ "first": true,
+ "payload": ""
+}
+
+

Example (upon SEND_TICK with a payload of arbitrary string):

+
+
+
{
+ "first": false,
+ "payload": "arbitrary string"
+}
+
+
@@ -1568,6 +1626,11 @@ Go https://github.com/mdirkse/i3ipc-go

+
  • +

    +https://github.com/i3/go-i3 +

    +
    • @@ -1618,11 +1681,6 @@ Python

  • -https://github.com/Ceryn/i3msg-python -

    -
    • -
  • -

    https://github.com/whitelynx/i3ipc (not maintained)

    • @@ -1785,6 +1843,8 @@ From here on out, send/receive all messages using the detected byte order.

    +

    Find an example implementation of this technique in +https://github.com/i3/go-i3/blob/master/byteorder.go

    diff --git a/docs/testsuite.html b/docs/testsuite.html index 8946765..375b246 100644 --- a/docs/testsuite.html +++ b/docs/testsuite.html @@ -175,10 +175,8 @@ with an appropriate configuration file and creates a folder for each run containing the appropriate i3 logfile for each testcase. The latest folder can always be found under the symlink latest/. Unless told differently, it will run the tests on a separate X server instance (using Xephyr).

    -

    Xephyr will open a window where you can inspect the running test. You can run -the tests without an X session with Xvfb, such as with xvfb-run -./complete-run. This will also speed up the tests significantly especially on -machines without a powerful video card.

    +

    Xephyr will open a window where you can inspect the running test. By default, +tests are run under Xvfb.

    Example invocation of complete-run.pl
    diff --git a/docs/userguide.html b/docs/userguide.html index d2e4c3a..d98a8c5 100644 --- a/docs/userguide.html +++ b/docs/userguide.html @@ -32,7 +32,6 @@ document.addEventListener("DOMContentLoaded", function(){asciidoc.footnotes(); a

    i3 User’s Guide

    Michael Stapelberg
    <michael@i3wm.org>
    -March 2013
    Table of Contents
    @@ -50,7 +49,7 @@ mailing list.

    1. Default keybindings

    For the "too long; didn’t read" people, here is an overview of the default -keybindings (click to see the full size image):

    +keybindings (click to see the full-size image):

    Keys to use with $mod (Alt):

    @@ -78,7 +77,8 @@ above, just decline i3-config-wizard’s offer and base your config on

    Throughout this guide, the keyword $mod will be used to refer to the configured modifier. This is the Alt key (Mod1) by default, with the Windows -key (Mod4) being a popular alternative.

    +key (Mod4) being a popular alternative that largely prevents conflicts with +application-defined shortcuts.

    2.1. Opening terminals and moving around

    One very basic operation is opening a new terminal. By default, the keybinding @@ -248,7 +248,7 @@ finally the windows themselves. In previous versions of i3 we had multiple lists out to be complicated to use (snapping), understand and implement.

    3.1. The tree consists of Containers

    -

    The building blocks of our tree are so called Containers. A Container can +

    The building blocks of our tree are so-called Containers. A Container can host a window (meaning an X11 window, one that you can actually see and use, like a browser). Alternatively, it could contain one or more Containers. A simple example is the workspace: When you start i3 with a single monitor, a @@ -311,7 +311,7 @@ of splits can be.

    vertically split terminals on the right, focus is on the bottom right one. When you open a new terminal, it will open below the current one.

    So, how can you open a new terminal window to the right of the current one? -The solution is to use focus parent ($mod+a by default), which will focus the Parent Container of +The solution is to use focus parent, which will focus the Parent Container of the current Container. In this case, you would focus the Vertical Split Container which is inside the horizontally oriented workspace. Thus, now new windows will be opened to the right of the Vertical Split Container:

    @@ -576,7 +576,7 @@ mode "$mode_launcher" {

    4.6. The floating modifier

    To move floating windows with your mouse, you can either grab their titlebar -or configure the so called floating modifier which you can then press and +or configure the so-called floating modifier which you can then press and click anywhere in the window itself to move it. The most common setup is to use the same key you use for managing windows (Mod1 for example). Then you can press Mod1, click into a window using your left mouse button, and drag @@ -651,33 +651,35 @@ start.

    -

    4.10. Border style for new windows

    +

    4.10. Default border style for new windows

    This option determines which border style new windows will have. The default is -normal. Note that new_float applies only to windows which are starting out as +normal. Note that default_floating_border applies only to windows which are starting out as floating windows, e.g., dialog windows, but not windows that are floated later on.

    Syntax:

    -
    new_window normal|none|pixel
-new_window normal|pixel <px>
-new_float normal|none|pixel
-new_float normal|pixel <px>
    +
    default_border normal|none|pixel
+default_border normal|pixel <px>
+default_floating_border normal|none|pixel
+default_floating_border normal|pixel <px>
    +

    Please note that new_window and new_float have been deprecated in favor of the above options +and will be removed in a future release. We strongly recommend using the new options instead.

    Example:

    -
    new_window pixel
    +
    default_border pixel

    The "normal" and "pixel" border styles support an optional border width in pixels:

    Example:

    -
    # The same as new_window none
-new_window pixel 0
+
    # The same as default_border none
+default_border pixel 0
 
 # A 3 px border
-new_window pixel 3
    
+default_border pixel 3
    @@ -810,13 +812,17 @@ starts up being named Firefox, and only when Vimperator is loaded does the title change. As i3 will get the title as soon as the application maps the window (mapping means actually displaying it on the screen), you’d need to have to match on Firefox in this case.

    +

    You can also assign a window to show up on a specific output. You can use RandR +names such as VGA1 or names relative to the output with the currently focused +workspace such as left and down.

    Assignments are processed by i3 in the order in which they appear in the config file. The first one which matches the window wins and later assignments are not considered.

    Syntax:

    -
    assign <criteria> [→] [workspace] <workspace>
    +
    assign <criteria> [→] [workspace] [number] <workspace>
+assign <criteria> [→] output left|right|up|down|primary|<output>

    Examples:

    @@ -833,10 +839,27 @@ assign [class="^URxvt$"] → 2 # Assignment to a named workspace assign [class="^URxvt$"] → work +# Assign to the workspace with number 2, regardless of name +assign [class="^URxvt$"] → number 2 + +# You can also specify a number + name. If the workspace with number 2 exists, assign will skip the text part. +assign [class="^URxvt$"] → number "2: work" + # Start urxvt -name irssi -assign [class="^URxvt$" instance="^irssi$"] → 3 +assign [class="^URxvt$" instance="^irssi$"] → 3 + +# Assign urxvt to the output right of the current one +assign [class="^URxvt$"] → output right + +# Assign urxvt to the primary output +assign [class="^URxvt$"] → output primary +
    +

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

    +
    +
    +
    xrandr --output <output> --primary
    -

    Note that the arrow is not required, it just looks good :-). If you decide to +

    Also, the arrow is not required, it just looks good :-). If you decide to use it, it has to be a UTF-8 encoded arrow, not -> or something like that.

    To get the class and instance, you can use xprop. After clicking on the window, you will see the following output:

    @@ -1113,24 +1136,35 @@ Leave fullscreen mode.

    4.24. 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 -be set on that container. This is the default behavior so you can navigate to -all your windows without having to use focus parent.

    +

    By default, when in a container with several windows or child containers, the +opposite window will be focused when trying to move the focus over the edge of +a container (and there are no other containers in that direction) — the focus +wraps.

    +

    If desired, you can disable this behavior by setting the focus_wrapping +configuration directive to the value no.

    +

    When enabled, focus wrapping does not occur by default if there is another +window or container in the specified direction, and focus will instead be set +on that window or container. This is the default behavior so you can navigate +to all your windows without having to use focus parent.

    If you want the focus to always wrap and you are aware of using focus -parent to switch to different containers, you can use the -force_focus_wrapping configuration directive. After enabling it, the focus -will always wrap.

    +parent to switch to different containers, you can instead set focus_wrapping +to the value force.

    Syntax:

    -
    force_focus_wrapping yes|no
    +
    focus_wrapping yes|no|force
+
+# Legacy syntax, equivalent to "focus_wrapping force"
+force_focus_wrapping yes
    -

    Example:

    +

    Examples:

    -
    force_focus_wrapping yes
    +
    # Disable focus wrapping
+focus_wrapping no
+
+# Force focus wrapping
+focus_wrapping force
    @@ -1466,7 +1500,7 @@ and will be removed in a future release. We strongly recommend using the more ge

    Syntax:

    -
    bindsym button<n> <command>
    +
    bindsym [--release] button<n> <command>

    Example:

    @@ -1474,6 +1508,8 @@ and will be removed in a future release. We strongly recommend using the more ge 
    bar {
     # disable clicking on workspace buttons
     bindsym button1 nop
+    # Take a screenshot by right clicking on the bar
+    bindsym --release button3 exec --no-startup-id import /tmp/latest-screenshot.png
     # execute custom script when scrolling downwards
     bindsym button5 exec ~/.i3/scripts/custom_wheel_down
 }
    @@ -2151,6 +2187,15 @@ bindsym $mod+t floating toggle available:

    +<criteria> +
    +
    +

    + Sets focus to the container that matches the specified criteria. + See [command_criteria]. +

    +
    +
    left|right|up|down
    @@ -2212,14 +2257,18 @@ output

    Syntax:

    -
    focus left|right|down|up
+
    <criteria> focus
+focus left|right|down|up
 focus parent|child|floating|tiling|mode_toggle
 focus output left|right|up|down|primary|<output>

    Examples:

    -
    # Focus container on the left, bottom, top, right
+
    # Focus firefox
+bindsym $mod+F1 [class="Firefox"] focus
+
+# Focus container on the left, bottom, top, right
 bindsym $mod+j focus left
 bindsym $mod+k focus down
 bindsym $mod+l focus up
@@ -2516,45 +2565,40 @@ bindsym $mod+x move container to output VGA1
 # Put this window on the primary output.
 bindsym $mod+x move container to 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

    -
    -
    -
    === Moving containers/windows to marks
-
-To move a container to another container with a specific mark (see <<vim_like_marks>>),
-you can use the following command.
-
-The window will be moved right after the marked container in the tree, i.e., it ends up
+
    +
    +

    6.11. Moving containers/windows to marks

    +

    To move a container to another container with a specific mark (see [vim_like_marks]), +you can use the following command.

    +

    The window will be moved right after the marked container in the tree, i.e., it ends up in the same position as if you had opened a new window when the marked container was focused. If the mark is on a split container, the window will appear as a new child -after the currently focused child within that container. - -*Syntax*: +after the currently focused child within that container.

    +

    Syntax:

    +
    +
    +
    move window|container to mark <mark>
    -
    -
    -
    -
    -

    7. move window|container to mark <mark>

    -

    Example:

    for_window [instance="tabme"] move window to mark target
    +
    -

    7.1. Resizing containers/windows

    +

    6.12. Resizing containers/windows

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

    Syntax:

    resize grow|shrink <direction> [<px> px [or <ppt> ppt]]
-resize set <width> [px] <height> [px]
    +resize set <width> [px | ppt] <height> [px | ppt]

    Direction can either be one of up, down, left or right. Or you can be less specific and use width or height, in which case i3 will take/give @@ -2562,8 +2606,10 @@ space from all the other containers. The optional pixel argument specifies by how many pixels a floating container should be grown or shrunk (the default is 10 pixels). The ppt argument means percentage points and specifies by how many percentage points a tiling container should be grown or shrunk (the -default is 10 percentage points). Note that resize set will only work for -floating containers.

    +default is 10 percentage points).

    +

    Notes about resize set: a value of 0 for <width> or <height> means "do +not resize in this direction", and resizing a tiling container by px is not +implemented.

    It is recommended to define bindings for resizing in a dedicated binding mode. See [binding_modes] and the example in the i3 default config for more @@ -2575,7 +2621,7 @@ context.

    -

    7.2. Jumping to specific windows

    +

    6.13. 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 @@ -2596,7 +2642,7 @@ bindsym $mod+a [class="urxvt" title="VIM"] focus

    -

    7.3. VIM-like marks (mark/goto)

    +

    6.14. 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 @@ -2639,7 +2685,7 @@ unmark irssi

    -

    7.4. Window title format

    +

    6.15. 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 @@ -2697,7 +2743,7 @@ for_window [class="(?i)firefox"] title_format "<span foreground='red'>%tit

    -

    7.5. Changing border style

    +

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

    @@ -2726,7 +2772,7 @@ bindsym $mod+u border none
    -

    7.6. Enabling shared memory logging

    +

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

    @@ -2750,7 +2796,7 @@ i3-msg shmlog $((50*1024*1024))
    -

    7.7. Enabling debug logging

    +

    6.18. 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 @@ -2768,7 +2814,7 @@ bindsym $mod+x debuglog toggle

    -

    7.8. Reloading/Restarting/Exiting

    +

    6.19. 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 @@ -2783,7 +2829,7 @@ bindsym $mod+Shift+e exit

    -

    7.9. Scratchpad

    +

    6.20. 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. @@ -2818,7 +2864,7 @@ bindsym mod4+s [title="^Sup ::"] scratchpad show

    -

    7.10. Nop

    +

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

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

    7.11. i3bar control

    +

    6.22. 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 @@ -2872,7 +2918,7 @@ bindsym $mod+Shift+b bar mode invisible bar-1

    -

    8. Multiple monitors

    +

    7. 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 @@ -2895,7 +2941,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).

    -

    8.1. Configuring your monitors

    +

    7.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. @@ -2958,7 +3004,7 @@ only what you can see in xrandr.

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

    -

    8.2. Interesting configuration for multi-monitor environments

    +

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

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

    9. i3 and the rest of your software world

    +

    8. i3 and the rest of your software world

    -

    9.1. Displaying a status line

    +

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

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

    -

    9.2. Giving presentations (multi-monitor)

    +

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

    -

    9.2.1. Case 1: everybody gets the same output

    +

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

    @@ -3035,7 +3081,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).

    -

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

    +

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

    -- 2.39.5