From 6316c876a2ac2e6d695cfcfd20bc51da7482f40b Mon Sep 17 00:00:00 2001 From: Michael Stapelberg Date: Sun, 4 Nov 2018 14:50:46 +0100 Subject: [PATCH] update docs for 4.16 --- _docs/debugging | 5 +- _docs/i3bar-protocol | 9 ++- _docs/ipc | 29 ++++++++ _docs/layout-saving | 12 ++-- _docs/userguide | 107 +++++++++++++++++++--------- docs/debugging.html | 7 +- docs/hacking-howto.html | 2 +- docs/i3bar-protocol.html | 17 ++++- docs/ipc.html | 40 ++++++++++- docs/layout-saving.html | 14 ++-- docs/multi-monitor.html | 2 +- docs/testsuite.html | 2 +- docs/userguide.html | 150 ++++++++++++++++++++++++--------------- docs/wsbar.html | 2 +- 14 files changed, 278 insertions(+), 120 deletions(-) diff --git a/_docs/debugging b/_docs/debugging index 9734b21..2343a74 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.15 +== Verify you are using i3 ≥ 4.16 Only the latest major version of i3 is supported. To verify which version you are running, use: @@ -160,7 +160,8 @@ flood kicks. == Debugging i3bar -To debug i3bar problems, add +verbose yes+ to all +bar {}+ blocks in your i3 +To debug i3bar problems, use the +--verbose+ commandline parameter, +or add +verbose yes+ to all +bar {}+ blocks in your i3 config, reload your config and then restart all i3bar instances like this: --------------------------------------------------------------------- diff --git a/_docs/i3bar-protocol b/_docs/i3bar-protocol index cf86531..826cae5 100644 --- a/_docs/i3bar-protocol +++ b/_docs/i3bar-protocol @@ -107,7 +107,7 @@ stop_signal:: processing. The default value (if none is specified) is SIGSTOP. cont_signal:: - Specify to i3bar the signal (as an integer)to send to continue your + Specify to i3bar the signal (as an integer) to send to continue your processing. The default value (if none is specified) is SIGCONT. click_events:: @@ -118,7 +118,8 @@ click_events:: full_text:: The +full_text+ will be displayed by i3bar on the status line. This is the - only required key. + only required key. If +full_text+ is an empty string, the block will be + skipped. short_text:: Where appropriate, the +short_text+ (string) entry should also be provided. It will be used in case the status line needs to be shortened @@ -242,6 +243,9 @@ relative_x, relative_y:: of the block width, height:: Width and height (in px) of the block +modifiers:: + An array of the modifiers active when the click occurred. The order in which + modifiers are listed is not guaranteed. *Example*: ------------------------------------------ @@ -249,6 +253,7 @@ width, height:: "name": "ethernet", "instance": "eth0", "button": 1, + "modifiers": ["Shift", "Mod1"], "x": 1320, "y": 1400, "relative_x": 12, diff --git a/_docs/ipc b/_docs/ipc index 8b767ad..bcf8df1 100644 --- a/_docs/ipc +++ b/_docs/ipc @@ -65,6 +65,7 @@ to do that). | 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. +| 11 | +SYNC+ | <<_sync_reply,SYNC>> | Sends an i3 sync event with the specified random value to the specified window. |====================================================== So, a typical message could look like this: @@ -327,6 +328,8 @@ window (integer):: 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). +window_properties (map):: + X11 window properties title, instance, class, window_role and transient_for. urgent (bool):: Whether this container (window, split container, floating container or workspace) has the urgency hint set, directly or indirectly. All parent @@ -422,6 +425,12 @@ JSON dump: "width": 1280, "height": 782 }, + "window_properties": { + "class": "Evince", + "instance": "evince", + "title": "Properties", + "transient_for": 52428808 + }, "floating_nodes": [], "nodes": [ @@ -654,6 +663,18 @@ events generated prior to the +SEND_TICK+ message (happened-before relation). { "success": true } ------------------- +[[_sync_reply]] +=== SYNC reply + +The reply is a map containing the "success" member. After the reply was +received, the https://i3wm.org/docs/testsuite.html#i3_sync[i3 sync message] was +responded to. + +*Example:* +------------------- +{ "success": true } +------------------- + == Events [[events]] @@ -672,6 +693,14 @@ program does not want to cope which such kinds of race conditions (an event based library may not have a problem here), I suggest you create a separate connection to receive events. +If an event message needs to be sent and the socket is not writeable (write +returns EAGAIN, happens when the socket doesn't have enough buffer space for +writing new data) then i3 uses a queue system to store outgoing messages for +each client. This is combined with a timer: if the message queue for a client is +not empty and no data where successfully written in the past 10 seconds, the +connection is killed. Practically, this means that your client should try to +always read events from the socket to avoid having its connection closed. + === Subscribing to events By sending a message of type SUBSCRIBE with a JSON-encoded array as payload diff --git a/_docs/layout-saving b/_docs/layout-saving index e90ecad..f31b5e2 100644 --- a/_docs/layout-saving +++ b/_docs/layout-saving @@ -219,13 +219,15 @@ the window which matches any of the criteria. As an example: A layout file as generated by +i3-save-tree(1)+ is not strictly valid JSON: -1. Layout files contain multiple “JSON documents” on the top level, whereas the - JSON standard only allows precisely one “document” (array or hash). +1. Layout files contain multiple “JSON texts” at the top level. The JSON + standard doesn't prohibit this, but in practice most JSON parsers only + allow precisely one “text” per document/file, and will mark multiple texts + as invalid JSON. -2. Layout files contain comments which are not standardized, but understood by - many parsers. +2. Layout files contain comments which are not allowed by the JSON standard, + but are understood by many parsers. -Both deviations from the JSON standard are to make manual editing by humans +Both of these deviations from the norm are to make manual editing by humans easier. In case you are writing a more elaborate tool for manipulating these layouts, you can either use a JSON parser that supports these deviations (for example libyajl), transform the layout file to a JSON-conforming file, or diff --git a/_docs/userguide b/_docs/userguide index a491d4e..91060ab 100644 --- a/_docs/userguide +++ b/_docs/userguide @@ -245,9 +245,11 @@ 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+, 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+: +the current +Container+. In default configuration, use +$mod+a+ to navigate one ++Container+ up the tree (you can repeat this multiple times until you get to the ++Workspace 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+: image::tree-shot3.png["shot3",title="Focus parent, then open new terminal"] @@ -585,6 +587,16 @@ workspace_layout default|stacking|tabbed workspace_layout tabbed --------------------- +=== Window title alignment + +This option determines the window title's text alignment. +Default is +left+ + +*Syntax*: +--------------------------------------------- +title_align left|center|right +--------------------------------------------- + === Default border style for new windows This option determines which border style new windows will have. The default is @@ -730,7 +742,8 @@ resource database to achieve an easily maintainable, consistent color theme across many X applications. Defining a resource will load this resource from the resource database and -assign its value to the specified variable. A fallback must be specified in +assign its value to the specified variable. This is done verbatim and the value +must therefore be in the format that i3 uses. A fallback must be specified in case the resource cannot be loaded from the database. *Syntax*: @@ -754,14 +767,23 @@ set_from_resource $black i3wm.color0 #000000 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 <>. It is recommended that you match on window classes -(and instances, when appropriate) instead of window titles whenever possible -because some applications first create their window, and then worry about -setting the correct title. Firefox with Vimperator comes to mind. The window -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. +see <>. The difference between +assign+ and ++for_window move to workspace+ is that the former will only be +executed when the application maps the window (mapping means actually displaying +it on the screen) but the latter will be executed whenever a window changes its +properties to something that matches the specified criteria. + +Thus, it is recommended that you match on window classes (and instances, when +appropriate) instead of window titles whenever possible because some +applications first create their window, and then worry about setting the correct +title. Firefox with Vimperator comes to mind. The window 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, you’d need to have to +match on 'Firefox' in this case. +Another known issue is with Spotify, which doesn't set the class hints when +mapping the window, meaning you'll have to use a +for_window+ rule to assign +Spotify to a specific workspace. +Finally, using +assign [tiling]+ and +assign [floating]+ is not supported. 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 @@ -887,7 +909,7 @@ the second screen and so on). *Syntax*: ------------------------------------- -workspace output +workspace output [output2]… ------------------------------------- The 'output' is the name of the RandR output you attach your screen to. On a @@ -906,12 +928,15 @@ monitor name is “Dell UP2414Q”. entire monitor, i3 will still use the entire area of the containing monitor rather than that of just the output's.) +You can specify multiple outputs. The first available will be used. + If you use named workspaces, they must be quoted: *Examples*: --------------------------- workspace 1 output LVDS1 -workspace 5 output VGA1 +workspace 2 output primary +workspace 5 output VGA1 LVDS1 workspace "2: vim" output VGA1 --------------------------- @@ -991,7 +1016,7 @@ ipc-socket ~/.i3/i3-ipc.sock ---------------------------- You can then use the +i3-msg+ application to perform any command listed in -the next section. +<>. === Focus follows mouse @@ -1117,6 +1142,7 @@ force_xinerama yes Also note that your output names are not descriptive (like +HDMI1+) when using Xinerama, instead they are counted up, starting at 0: +xinerama-0+, +xinerama-1+, … +[[workspace_auto_back_and_forth]] === Automatic back-and-forth when switching to the current workspace This configuration directive enables automatic +workspace back_and_forth+ (see @@ -1594,7 +1620,7 @@ bar { } ------------------------ -=== Strip workspace numbers +=== Strip workspace numbers/name Specifies whether workspace numbers should be displayed within the workspace buttons. This is useful if you want to have a named workspace that stays in @@ -1605,11 +1631,15 @@ the form "[n]:[NAME]" will display only the name. You could use this, for instance, to display Roman numerals rather than digits by naming your workspaces to "1:I", "2:II", "3:III", "4:IV", ... +When +strip_workspace_name+ is set to +yes+, any workspace that has a name of +the form "[n]:[NAME]" will display only the number. + The default is to display the full name within the workspace button. *Syntax*: ------------------------------ strip_workspace_numbers yes|no +strip_workspace_name yes|no ------------------------------ *Example*: @@ -1707,6 +1737,7 @@ bar { } -------------------------------------- +[[list_of_commands]] == List of commands Commands are what you bind to specific keypresses. You can also issue commands @@ -2025,10 +2056,13 @@ Use the +move+ command to move a container. # defaults to 10 pixels. move [ px] -# Moves the container either to a specific location -# or to the center of the screen. If 'absolute' is -# used, it is moved to the center of all outputs. -move [absolute] position [px] [px] +# Moves the container to the specified pos_x and pos_y +# coordinates on the screen. +move position [px] [px] + +# Moves the container to the center of the screen. +# If 'absolute' is used, it is moved to the center of +# all outputs. move [absolute] position center # Moves the container to the current position of the @@ -2113,8 +2147,8 @@ for_window [instance=notepad] sticky enable To change to a specific workspace, use the +workspace+ command, followed by the number or name of the workspace. Pass the optional flag -+--no-auto-back-and-forth+ to disable <> for this specific call -only. ++--no-auto-back-and-forth+ to disable <> for this +specific call only. To move containers to specific workspaces, use +move container to workspace+. @@ -2312,20 +2346,21 @@ If you want to resize containers/windows using your keyboard, you can use the *Syntax*: ------------------------------------------------------- resize grow|shrink [ px [or ppt]] -resize set [px | ppt] [px | ppt] +resize set [width] [px | ppt] +resize set height [px | ppt] +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 -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). +less specific and use +width+ or +height+, in which case i3 will take/give space +from all the other containers. The optional pixel argument specifies by how many +pixels a container should be grown or shrunk (the default is 10 pixels). The +optional ppt argument means "percentage points", and if specified it indicates +that a *tiling container* should be grown or shrunk by that many points, instead +of by the +px+ value. -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. +Note about +resize set+: a value of 0 for or means "do not +resize in this direction". It is recommended to define bindings for resizing in a dedicated binding mode. See <> and the example in the i3 @@ -2468,7 +2503,9 @@ To change the border of the current client, you can use +border normal+ to use t border (including window title), +border pixel 1+ to use a 1-pixel border (no window title) and +border none+ to make the client borderless. -There is also +border toggle+ which will toggle the different border styles. +There is also +border toggle+ which will toggle the different border styles. The +optional pixel argument can be used to specify the border width when switching +to the normal and pixel styles. Note that "pixel" refers to logical pixel. On HiDPI displays, a logical pixel may be represented by multiple physical pixels, so +pixel 1+ might not @@ -2476,8 +2513,8 @@ necessarily translate into a single pixel row wide border. *Syntax*: ----------------------------------------------- -border normal|pixel [] -border none|toggle +border normal|pixel|toggle [] +border none # legacy syntax, equivalent to "border pixel 1" border 1pixel diff --git a/docs/debugging.html b/docs/debugging.html index da9dca0..bfbb12e 100644 --- a/docs/debugging.html +++ b/docs/debugging.html @@ -4,7 +4,7 @@ - + i3: Debugging i3: How To @@ -44,7 +44,7 @@ process and/or need further help, do not hesitate to contact us!

-

1. Verify you are using i3 ≥ 4.15

+

1. Verify you are using i3 ≥ 4.16

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

@@ -230,7 +230,8 @@ flood kicks.

7. Debugging i3bar

-

To debug i3bar problems, add verbose yes to all bar {} blocks in your i3 +

To debug i3bar problems, use the --verbose commandline parameter, +or add verbose yes to all bar {} blocks in your i3 config, reload your config and then restart all i3bar instances like this:

diff --git a/docs/hacking-howto.html b/docs/hacking-howto.html index a55a82d..15e6c59 100644 --- a/docs/hacking-howto.html +++ b/docs/hacking-howto.html @@ -4,7 +4,7 @@ - + i3: Hacking i3: How To diff --git a/docs/i3bar-protocol.html b/docs/i3bar-protocol.html index e84e177..ffdc1f7 100644 --- a/docs/i3bar-protocol.html +++ b/docs/i3bar-protocol.html @@ -4,7 +4,7 @@ - + i3: i3bar input protocol @@ -172,7 +172,7 @@ cont_signal

- Specify to i3bar the signal (as an integer)to send to continue your + Specify to i3bar the signal (as an integer) to send to continue your processing. The default value (if none is specified) is SIGCONT.

@@ -197,7 +197,8 @@ full_text

The full_text will be displayed by i3bar on the status line. This is the - only required key. + only required key. If full_text is an empty string, the block will be + skipped.

@@ -423,6 +424,15 @@ width, height Width and height (in px) of the block

+
+modifiers +
+
+

+ An array of the modifiers active when the click occurred. The order in which + modifiers are listed is not guaranteed. +

+

Example:

@@ -431,6 +441,7 @@ width, height "name": "ethernet", "instance": "eth0", "button": 1, + "modifiers": ["Shift", "Mod1"], "x": 1320, "y": 1400, "relative_x": 12, diff --git a/docs/ipc.html b/docs/ipc.html index 350483e..12d7fe8 100644 --- a/docs/ipc.html +++ b/docs/ipc.html @@ -4,7 +4,7 @@ - + i3: IPC interface (interprocess communication) @@ -177,6 +177,12 @@ cellspacing="0" cellpadding="4">

TICK

Sends a tick event with the specified payload.

+ +

11

+

SYNC

+

SYNC

+

Sends an i3 sync event with the specified random value to the specified window.

+
@@ -656,6 +662,14 @@ window (integer)

+window_properties (map) +
+
+

+ X11 window properties title, instance, class, window_role and transient_for. +

+
+
urgent (bool)
@@ -826,6 +840,12 @@ VGA1 "width": 1280, "height": 782 }, + "window_properties": { + "class": "Evince", + "instance": "evince", + "title": "Properties", + "transient_for": 52428808 + }, "floating_nodes": [], "nodes": [ @@ -1213,6 +1233,17 @@ events generated prior to the SEND_TICK message (happened-before relati 
{ "success": true }
+
+

3.13. SYNC reply

+

The reply is a map containing the "success" member. After the reply was +received, the i3 sync message was +responded to.

+

Example:

+
+
+
{ "success": true }
+
+
@@ -1230,6 +1261,13 @@ situation can happen: You send a GET_WORKSPACES request but you receive a program does not want to cope which such kinds of race conditions (an event based library may not have a problem here), I suggest you create a separate connection to receive events.

+

If an event message needs to be sent and the socket is not writeable (write +returns EAGAIN, happens when the socket doesn’t have enough buffer space for +writing new data) then i3 uses a queue system to store outgoing messages for +each client. This is combined with a timer: if the message queue for a client is +not empty and no data where successfully written in the past 10 seconds, the +connection is killed. Practically, this means that your client should try to +always read events from the socket to avoid having its connection closed.

4.1. Subscribing to events

By sending a message of type SUBSCRIBE with a JSON-encoded array as payload diff --git a/docs/layout-saving.html b/docs/layout-saving.html index f97f2ce..cddd582 100644 --- a/docs/layout-saving.html +++ b/docs/layout-saving.html @@ -4,7 +4,7 @@ - + i3: Layout saving in i3 @@ -253,18 +253,20 @@ the window which matches any of the criteria. As an example:

  1. -Layout files contain multiple “JSON documents” on the top level, whereas the - JSON standard only allows precisely one “document” (array or hash). +Layout files contain multiple “JSON texts” at the top level. The JSON + standard doesn’t prohibit this, but in practice most JSON parsers only + allow precisely one “text” per document/file, and will mark multiple texts + as invalid JSON.

  2. -Layout files contain comments which are not standardized, but understood by - many parsers. +Layout files contain comments which are not allowed by the JSON standard, + but are understood by many parsers.

-

Both deviations from the JSON standard are to make manual editing by humans +

Both of these deviations from the norm are to make manual editing by humans easier. In case you are writing a more elaborate tool for manipulating these layouts, you can either use a JSON parser that supports these deviations (for example libyajl), transform the layout file to a JSON-conforming file, or diff --git a/docs/multi-monitor.html b/docs/multi-monitor.html index ab86e7c..f79e00a 100644 --- a/docs/multi-monitor.html +++ b/docs/multi-monitor.html @@ -4,7 +4,7 @@ - + i3: The multi-monitor situation diff --git a/docs/testsuite.html b/docs/testsuite.html index 375b246..3e3bdb6 100644 --- a/docs/testsuite.html +++ b/docs/testsuite.html @@ -4,7 +4,7 @@ - + i3: i3 testsuite diff --git a/docs/userguide.html b/docs/userguide.html index 4091926..3431a9a 100644 --- a/docs/userguide.html +++ b/docs/userguide.html @@ -4,7 +4,7 @@ - + i3: i3 User’s Guide @@ -312,9 +312,11 @@ 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, 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:

+the current Container. In default configuration, use $mod+a to navigate one +Container up the tree (you can repeat this multiple times until you get to the +Workspace 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:

shot3 @@ -651,7 +653,17 @@ start.

-

4.10. Default border style for new windows

+

4.10. Window title alignment

+

This option determines the window title’s text alignment. +Default is left

+

Syntax:

+
+
+
title_align left|center|right
+
+
+
+

4.11. Default border style for new windows

This option determines which border style new windows will have. The default is 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.

@@ -683,7 +695,7 @@ default_border pixel 3
-

4.11. Hiding borders adjacent to the screen edges

+

4.12. Hiding borders adjacent to the screen edges

You can hide container 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. The "smart" setting hides borders on @@ -701,7 +713,7 @@ multiple windows visible. Default is none.

-

4.12. Arbitrary commands for specific windows (for_window)

+

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

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

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

-

4.13. Don’t focus window upon opening

+

4.14. Don’t focus window upon opening

When a new window appears, it will be focused. The no_focus directive allows preventing this from happening and must be used in combination with [command_criteria].

Note that this does not apply to all cases, e.g., when feeding data into a running application @@ -748,7 +760,7 @@ combination with workspace_layout.

-

4.14. Variables

+

4.15. 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, @@ -774,14 +786,15 @@ it before starting i3 (for example in your ~/.xsession file).

loaded from the X resource database.

-

4.15. X resources

+

4.16. X resources

[variables] can also be created using a value configured in the X resource database. This is useful, for example, to avoid configuring color values within the i3 configuration. Instead, the values can be configured, once, in the X resource database to achieve an easily maintainable, consistent color theme across many X applications.

Defining a resource will load this resource from the resource database and -assign its value to the specified variable. A fallback must be specified in +assign its value to the specified variable. This is done verbatim and the value +must therefore be in the format that i3 uses. A fallback must be specified in case the resource cannot be loaded from the database.

Syntax:

@@ -801,17 +814,25 @@ set_from_resource $black i3wm.color0 #000000
-

4.16. Automatically putting clients on specific workspaces

+

4.17. 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 -(and instances, when appropriate) instead of window titles whenever possible -because some applications first create their window, and then worry about -setting the correct title. Firefox with Vimperator comes to mind. The window -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.

+see [command_criteria]. The difference between assign and +for_window <criteria> move to workspace is that the former will only be +executed when the application maps the window (mapping means actually displaying +it on the screen) but the latter will be executed whenever a window changes its +properties to something that matches the specified criteria.

+

Thus, it is recommended that you match on window classes (and instances, when +appropriate) instead of window titles whenever possible because some +applications first create their window, and then worry about setting the correct +title. Firefox with Vimperator comes to mind. The window 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, you’d need to have to +match on Firefox in this case. +Another known issue is with Spotify, which doesn’t set the class hints when +mapping the window, meaning you’ll have to use a for_window rule to assign +Spotify to a specific workspace. +Finally, using assign [tiling] and assign [floating] is not supported.

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.

@@ -891,7 +912,7 @@ exec --no-startup-id i3-msg 'workspace 3; exec iceweasel; workspace 1'
-

4.17. Automatically starting applications on i3 startup

+

4.18. 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 @@ -918,7 +939,7 @@ exec --no-startup-id urxvt

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

-

4.18. Automatically putting workspaces on specific screens

+

4.19. 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 @@ -927,7 +948,7 @@ the second screen and so on).

Syntax:

-
workspace <workspace> output <output>
+
workspace <workspace> output <output1> [output2]…

The output is the name of the RandR output you attach your screen to. On a laptop, you might have VGA1 and LVDS1 as output names. You can see the @@ -942,17 +963,19 @@ monitor name is “Dell UP2414Q”.

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

+

You can specify multiple outputs. The first available will be used.

If you use named workspaces, they must be quoted:

Examples:

workspace 1 output LVDS1
-workspace 5 output VGA1
+workspace 2 output primary
+workspace 5 output VGA1 LVDS1
 workspace "2: vim" output VGA1
-

4.19. Changing colors

+

4.20. Changing colors

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

Syntax:

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

-

4.20. Interprocess communication

+

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

@@ -1057,10 +1080,10 @@ user can create that directory.

ipc-socket ~/.i3/i3-ipc.sock

You can then use the i3-msg application to perform any command listed in -the next section.

+[list_of_commands].

-

4.21. Focus follows mouse

+

4.22. Focus follows mouse

By default, window focus follows your mouse movements as the mouse crosses window borders. 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 @@ -1079,7 +1102,7 @@ currently active window (for example to click on links in your browser window).<

-

4.22. Mouse warping

+

4.23. Mouse warping

By default, when switching focus to a window on a different output (e.g. focusing a window on workspace 3 on output VGA-1, coming from workspace 2 on LVDS-1), the mouse cursor is warped to the center of that window.

@@ -1098,7 +1121,7 @@ behavior described above.

-

4.23. Popups during fullscreen mode

+

4.24. 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). @@ -1135,7 +1158,7 @@ Leave fullscreen mode.

-

4.24. Focus wrapping

+

4.25. Focus wrapping

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 @@ -1168,7 +1191,7 @@ focus_wrapping force

-

4.25. Forcing Xinerama

+

4.26. Forcing Xinerama

As explained in-depth in https://i3wm.org/docs/multi-monitor.html, some X11 video drivers (especially the nVidia binary driver) only provide support for Xinerama instead of RandR. In such a situation, i3 must be told to use the @@ -1191,7 +1214,7 @@ that’s it).

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

-

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

+

4.27. 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 @@ -1209,7 +1232,7 @@ came from now, you can just press $mod+2 again to switch back to "1: www".

-

4.27. Delaying urgency hint reset on workspace change

+

4.28. Delaying urgency hint reset on workspace change

If an application on another workspace sets an urgency hint, switching to this workspace may lead to immediate focus of the application, which also means the window decoration color would be immediately reset to client.focused. This @@ -1231,7 +1254,7 @@ value to 0 disables this feature.

-

4.28. Focus on window activation

+

4.29. Focus on window activation

If a window is activated, e.g., via google-chrome www.google.com, it may request to take focus. Since this may not preferable, different reactions can be configured.

Note that this may not affect windows that are being opened. To prevent new windows @@ -1279,7 +1302,7 @@ none

-

4.29. Drawing marks on window decoration

+

4.30. Drawing marks on window decoration

If activated, marks (see [vim_like_marks]) on windows are drawn in their window decoration. However, any mark starting with an underscore in its name (_) will not be drawn even if this option is activated.

@@ -1296,7 +1319,7 @@ not be drawn even if this option is activated.

-

4.30. Line continuation

+

4.31. Line continuation

Config files support line continuation, meaning when you end a line in a backslash character (\), the line-break will be ignored by the parser. This feature can be used to create more readable configuration files. @@ -1709,7 +1732,7 @@ you want to display a statusline-only bar containing additional information.

-

5.13. Strip workspace numbers

+

5.13. Strip workspace numbers/name

Specifies whether workspace numbers should be displayed within the workspace buttons. This is useful if you want to have a named workspace that stays in order on the bar according to its number without displaying the number prefix.

@@ -1717,11 +1740,14 @@ order on the bar according to its number without displaying the number prefix.
+

When strip_workspace_name is set to yes, any workspace that has a name of +the form "[n]:[NAME]" will display only the number.

The default is to display the full name within the workspace button.

Syntax:

-
strip_workspace_numbers yes|no
+
strip_workspace_numbers yes|no
+strip_workspace_name yes|no

Example:

@@ -1888,7 +1914,7 @@ binding_mode
-

6. List of commands

+

6. List of commands

Commands are what you bind to specific keypresses. You can also issue commands at runtime without pressing a key by using the IPC interface. An easy way to @@ -2307,10 +2333,13 @@ bindsym $mod+x focus output primary # defaults to 10 pixels. move <left|right|down|up> [<px> px] -# Moves the container either to a specific location -# or to the center of the screen. If 'absolute' is -# used, it is moved to the center of all outputs. -move [absolute] position <pos_x> [px] <pos_y> [px] +# Moves the container to the specified pos_x and pos_y +# coordinates on the screen. +move position <pos_x> [px] <pos_y> [px] + +# Moves the container to the center of the screen. +# If 'absolute' is used, it is moved to the center of +# all outputs. move [absolute] position center # Moves the container to the current position of the @@ -2414,8 +2443,8 @@ for_window [instance=notepad] sticky enable

6.8. Changing (named) workspaces/moving to workspaces

To change to a specific workspace, use the workspace command, followed by the number or name of the workspace. Pass the optional flag ---no-auto-back-and-forth to disable [back_and_forth] for this specific call -only.

+--no-auto-back-and-forth to disable [workspace_auto_back_and_forth] for this +specific call only.

To move containers to specific workspaces, use move container to workspace.

You can also switch to the next and previous workspace with the commands workspace next and workspace prev, which is handy, for example, if you have @@ -2598,18 +2627,19 @@ after the currently focused child within that container.

resize grow|shrink <direction> [<px> px [or <ppt> ppt]]
-resize set <width> [px | ppt] <height> [px | ppt]
+resize set [width] <width> [px | ppt] +resize set height <height> [px | ppt] +resize set [width] <width> [px | ppt] [height] <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 -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).

-

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.

+less specific and use width or height, in which case i3 will take/give space +from all the other containers. The optional pixel argument specifies by how many +pixels a container should be grown or shrunk (the default is 10 pixels). The +optional ppt argument means "percentage points", and if specified it indicates +that a tiling container should be grown or shrunk by that many points, instead +of by the px value.

+

Note about resize set: a value of 0 for <width> or <height> means "do not +resize in this direction".

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 @@ -2747,15 +2777,17 @@ for_window [class="(?i)firefox"] title_format "<span foreground='red'>%tit

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.

-

There is also border toggle which will toggle the different border styles.

+

There is also border toggle which will toggle the different border styles. The +optional pixel argument can be used to specify the border width when switching +to the normal and pixel styles.

Note that "pixel" refers to logical pixel. On HiDPI displays, a logical pixel may be represented by multiple physical pixels, so pixel 1 might not necessarily translate into a single pixel row wide border.

Syntax:

-
border normal|pixel [<n>]
-border none|toggle
+
border normal|pixel|toggle [<n>]
+border none
 
 # legacy syntax, equivalent to "border pixel 1"
 border 1pixel

diff --git a/docs/wsbar.html b/docs/wsbar.html
index b598f77..2dc13aa 100644
--- a/docs/wsbar.html
+++ b/docs/wsbar.html
@@ -4,7 +4,7 @@
 
 
 
-
+
 i3: External workspace bars
 
 
-- 
2.39.2