Optionally change i3bar color on focused output, implements #2020

[i3/i3] / docs / userguide

diff --git a/docs/userguide b/docs/userguide
index a94896cc4ac1f186d8f4b9c104072ccca1393d2b..ca39757aca41de2ce6100e35a62baa7003d466fe 100644 (file)
--- a/docs/userguide
+++ b/docs/userguide
@@ -1529,6 +1529,15 @@ statusline::
        Text color to be used for the statusline.
 separator::
        Text color to be used for the separator.
+focused_background::
+       Background color of the bar on the currently focused monitor output. If
+       not used, the color will be taken from +background+.
+focused_statusline::
+       Text color to be used for the statusline on the currently focused
+       monitor output. If not used, the color will be taken from +statusline+.
+focused_separator::
+       Text color to be used for the separator on the currently focused
+       monitor output. If not used, the color will be taken from +separator+.
 focused_workspace::
        Border, background and text color for a workspace button when the workspace
        has focus.
@@ -1659,10 +1668,13 @@ workspace::
        the special value +\_\_focused__+ to match all windows in the currently
        focused workspace.
 con_mark::
-       Compares the mark set for this container, see <<vim_like_marks>>.
+        Compares the marks set for this container, see <<vim_like_marks>>. A
+        match is made if any of the container's marks matches the specified
+        mark.
 con_id::
        Compares the i3-internal container ID, which you can get via the IPC
-       interface. Handy for scripting.
+       interface. Handy for scripting. Use the special value +\_\_focused__+
+       to match only the currently focused window.
 
 The criteria +class+, +instance+, +role+, +title+, +workspace+ and +mark+ are
 actually regular expressions (PCRE). See +pcresyntax(3)+ or +perldoc perlre+ for
@@ -1881,8 +1893,11 @@ for_window [instance=notepad] sticky enable
 === 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. To move containers to specific workspaces, use
-+move container to workspace+.
+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.
+
+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
@@ -1910,16 +1925,16 @@ back_and_forth+; likewise, you can move containers to the previously focused
 workspace using +move container to workspace back_and_forth+.
 
 *Syntax*:
------------------------------------
+--------------------------------------------------------------------------------
 workspace next|prev|next_on_output|prev_on_output
 workspace back_and_forth
-workspace <name>
-workspace number <name>
+workspace [--no-auto-back-and-forth] <name>
+workspace [--no-auto-back-and-forth] number <name>
 
-move [window|container] [to] workspace <name>
-move [window|container] [to] workspace number <name>
+move [--no-auto-back-and-forth] [window|container] [to] workspace <name>
+move [--no-auto-back-and-forth] [window|container] [to] workspace number <name>
 move [window|container] [to] workspace prev|next|current
------------------------------------
+--------------------------------------------------------------------------------
 
 *Examples*:
 -------------------------
@@ -2113,24 +2128,36 @@ for this purpose: It lets you input a command and sends the command to i3. It
 can also prefix this command and display a custom prompt for the input dialog.
 
 The additional +--toggle+ option will remove the mark if the window already has
-this mark, add it if the window has none or replace the current mark if it has
-another mark.
+this mark or add it otherwise. Note that you may need to use this in
+combination with +--add+ (see below) as any other marks will otherwise be
+removed.
+
+By default, a window can only have one mark. You can use the +--add+ flag to
+put more than one mark on a window.
 
 Refer to <<show_marks>> if you don't want marks to be shown in the window decoration.
 
 *Syntax*:
-------------------------------
-mark [--toggle] <identifier>
+----------------------------------------------
+mark [--add|--replace] [--toggle] <identifier>
 [con_mark="identifier"] focus
 unmark <identifier>
-------------------------------
+----------------------------------------------
 
 *Example (in a terminal)*:
-------------------------------
-$ i3-msg mark irssi
-$ i3-msg '[con_mark="irssi"] focus'
-$ i3-msg unmark irssi
-------------------------------
+---------------------------------------------------------
+# marks the focused container
+mark irssi
+
+# focus the container with the mark "irssi"
+'[con_mark="irssi"] focus'
+
+# remove the mark "irssi" from whichever container has it
+unmark irssi
+
+# remove all marks on all firefox windows
+[class="(?i)firefox"] unmark
+---------------------------------------------------------
 
 ///////////////////////////////////////////////////////////////////
 TODO: make i3-input replace %s