add user-contributed article about workspace switching by captnfab

diff --git a/docs/index.html b/docs/index.html
index 6f14e6e4d3ce27bc51db02426fd622e3c99f4ff8..aa3a7b3c51d2a7cb12e43fde76f32ef97f6691cc 100644 (file)
--- a/docs/index.html
+++ b/docs/index.html
@@ -119,6 +119,13 @@ Introduces py3status, a wrapper script for i3status which is easily extensible.
 Where and how to order official i3 T-shirts.
 </p>
 
+<p>
+<a href="/docs/user-contributed/workspace-current-output.html"><strong>Switch to workspaces on the current output</strong></a>
+<span class="author">(2014-08, by captnfab)</span><br>
+When switching workspaces, i3 sets focus to the output of the target workspace.
+With the script that is presented in this article, you always stay on the same
+output, and instead the workspace is moved.
+</p>
 
 </div>
 

diff --git a/docs/user-contributed/workspace-current-output.html b/docs/user-contributed/workspace-current-output.html
new file mode 100644 (file)
index 0000000..7c9b783
--- /dev/null
+++ b/docs/user-contributed/workspace-current-output.html
@@ -0,0 +1,110 @@
+---
+layout: default
+title: Docs
+group: Docs
+---
+<div id="content" class="usergen">
+
+<h1>User-contributed article: Move a given workspace to active output</h1>
+
+<h2>Introduction</h2>
+
+<p>Assume you have multiple monitors, and various workspaces on each of them.</p>
+
+<p>You have some workspace 1 active on monitor A, and you want to jump to
+workspace 2. The default behavior, using the built-in command <code>workspace 2</code>
+is to display the workspace 2 on the screen it belongs to.</p>
+
+<p>Another legitimate use-case would be to display the workspace 2 on the
+currently active screen.</p>
+
+<p>Unfortunately, there is no built-in command in i3 to achieve that, yet. However,
+thanks to the IPC interface, it is possible to write an external script
+achieving that.</p>
+
+<h2>Installation</h2>
+
+<p>First, we need to create an executable script doing the job thanks to the <a href="/docs/ipc.html">IPC</a> interface.
+In this article, we will assume the script is stored in <code>~/.config/i3/switch-workspace.py</code></p>
+
+<p>Here is a possible implementation of the script:</p>
+
+<pre>
+#!/usr/bin/env python
+
+from json import loads
+from os import popen
+from sys import argv
+
+def ipc_query(req="command", msg=""):
+    ans = popen("i3-msg -t " + req + " " +  msg).readlines()[0]
+    return loads(ans)
+
+if __name__ == "__main__":
+    # Usage &amp; checking args
+    if len(argv) != 2:
+        print "Usage: switch-workspace.py name-of-workspace"
+        exit(-1)
+
+    newworkspace = argv[1]
+
+    # Retrieving active display
+    active_display = None
+    for w in ipc_query(req="get_workspaces"):
+        if w['focused']:
+            active_display = w['output']
+
+    # Moving workspace to active display
+    print ipc_query(msg="'workspace " + newworkspace + "; move workspace to output " + active_display + "; workspace " + newworkspace + "'")
+</pre>
+
+<p>This script uses i3-msg directly, but if you have several IPC scripts, or more
+complex ones, or if you use quotes in your workspaces' names you may want to
+use the <a href="https://github.com/ziberna/i3-py">python i3-ipc bindings</a>
+as done in <a href="/docs/user-contributed/swapping-workspaces.html">this article</a>
+(however, in this case, you might have to add some bindings to the library to
+implement chained command since sequentiality is critical in this script).</p>
+
+<p>Do not forget to make the script executable, usually, the following
+command, assuming you adopted the naming of our article, should work:</p>
+
+<pre>
+chmod u+x ~/.config/i3/switch-workspace.py
+</pre>
+
+<h2>Configuration</h2>
+
+<p>Once the script is created and made executable, the last step is to add the
+corresponding bindings in your i3 conf file.</p>
+
+<p>Basically, one way to do that is to replace the <code>workspace X</code> bindings with
+<code>exec --no-startup-id ~/.config/i3/switch-workspace.py X</code>.</p>
+
+<p>For a standard <em>fr bépo</em> keyboard layout, this will result in:</p>
+
+<pre>
+# switch to workspace
+bindsym $mod+quotedbl exec --no-startup-id ~/.config/i3/switch-workspace.py 1
+bindsym $mod+guillemotleft exec --no-startup-id ~/.config/i3/switch-workspace.py 2
+bindsym $mod+guillemotright exec --no-startup-id ~/.config/i3/switch-workspace.py 3
+bindsym $mod+parenleft exec --no-startup-id ~/.config/i3/switch-workspace.py 4
+bindsym $mod+parenright exec --no-startup-id ~/.config/i3/switch-workspace.py 5
+bindsym $mod+at exec --no-startup-id ~/.config/i3/switch-workspace.py 6
+bindsym $mod+plus exec --no-startup-id ~/.config/i3/switch-workspace.py 7
+bindsym $mod+minus exec --no-startup-id ~/.config/i3/switch-workspace.py 8
+bindsym $mod+slash exec --no-startup-id ~/.config/i3/switch-workspace.py 9
+bindsym $mod+asterisk exec --no-startup-id ~/.config/i3/switch-workspace.py 10
+</pre>
+
+<p>But of course, you will have to adapt this to your own keyboard layout.</p>
+
+<h2>References</h2>
+
+<ul>
+<li><a href="https://github.com/ziberna/i3-py">Python i3-ipc bindings</a></li>
+<li><a href="/docs/user-contributed/swapping-workspaces.html">Swapping workspaces</a></li>
+<li><a href="/docs/ipc.html">IPC interface</a></li>
+<li>A bug repport explaining <a href="http://bugs.i3wm.org/report/ticket/809">how to make the focus follow the moved workspace</a></li>
+</ul>
+
+<p>Author: <a href="http://captnfab.chezlefab.net/">captnfab</a>, 2014-08-02</p>