i3-input(1)
=========
Michael Stapelberg <michael+i3@stapelberg.de>
-v3.delta, November 2009
+v4.1, September 2011
== NAME
== SYNOPSIS
-i3-input [-s <socket>] [-
p <prefix>] [-l <limit>] [-P <prompt>] [-f <font>] [-v]
+i3-input [-s <socket>] [-
F <format>] [-l <limit>] [-P <prompt>] [-f <font>] [-v]
== DESCRIPTION
the user, and send it/them to i3. This is useful, for example, for the
mark/goto command.
+The -F option takes a format string. In this string, every occurence of %s is
+replaced by the user input.
+
== EXAMPLE
------------------------------------------------
-i3-input -p 'mark ' -l 1 -P 'Mark: '
+i3-input -F 'mark %s' -l 1 -P 'Mark: '
------------------------------------------------
== ENVIRONMENT
=== I3SOCK
-If no ipc-socket is specified on the commandline, this variable is used
-to determine the path, at wich the unix domain socket is expected, on which
-to connect to i3.
+i3-input handles the different sources of socket paths in the following order:
+
+* I3SOCK environment variable
+* I3SOCK gets overwritten by the -s parameter, if specified
+* if neither are available, i3-input reads the socket path from the X11
+ property, which is the recommended way
+* if everything fails, i3-input tries +/tmp/i3-ipc.sock+
+
+The socket path is necessary to connect to i3 and actually issue the command.
== SEE ALSO
# exit i3 (logs you out of your X session)
bindsym Mod1+Shift+e exit
-# Start i3bar to display a workspace bar (plus the system information i3status
-# finds out, if available)
-exec i3status | i3bar -d
+# display workspace buttons plus a statusline generated by i3status
+bar {
+ status_command i3status
+}
-------------------------------------------------------------
=== ~/.xsession
=== I3SOCK
This variable overwrites the IPC socket path (placed in
-/tmp/i3-%u/ipc-socket.%p by default, where %u is replaced with your UNIX
-username and %p is replaced with i3’s PID). The IPC socket is used by external
-programs like i3-msg(1) or i3bar(1).
+/tmp/i3-%u.XXXXXX/ipc-socket.%p by default, where %u is replaced with your UNIX
+username, %p is replaced with i3’s PID and XXXXXX is a string of random
+characters from the portable filename character set (see mkdtemp(3))). The IPC
+socket is used by external programs like i3-msg(1) or i3bar(1).
== TODO
IPC interface (interprocess communication)
==========================================
Michael Stapelberg <michael+i3@stapelberg.de>
-March 2010
+October 2011
This document describes how to interface with i3 from a separate process. This
is useful for example to remote-control i3 (to write test cases for example) or
The method of choice for IPC in our case is a unix socket because it has very
little overhead on both sides and is usually available without headaches in
most languages. In the default configuration file, the ipc-socket gets created
-in +/tmp/i3-%u/ipc-socket.%p+ where +%u+ is your UNIX username and +%p+ is the
-PID of i3.
+in +/tmp/i3-%u.XXXXXX/ipc-socket.%p+ where +%u+ is your UNIX username, +%p+ is
+the PID of i3 and XXXXXX is a string of random characters from the portable
+filename character set (see mkdtemp(3)). You can get the socketpath from i3 by
+calling +i3 --get-socketpath+.
All i3 utilities, like +i3-msg+ and +i3-input+ will read the +I3_SOCKET_PATH+
X11 property, stored on the X11 root window.
-------------------------------------------------------------
use IO::Socket::UNIX;
-my $sock = IO::Socket::UNIX->new(Peer => '/tmp/i3-ipc.sock');
+chomp(my $path = qx(i3 --get-socketpath));
+my $sock = IO::Socket::UNIX->new(Peer => $path);
-------------------------------------------------------------
== Sending messages to i3
Gets the layout tree. i3 uses a tree as data structure which includes
every container. The reply will be the JSON-encoded tree (see the reply
section).
+GET_MARKS (5)::
+ Gets a list of marks (identifiers for containers to easily jump to them
+ later). The reply will be a JSON-encoded list of window marks (see
+ reply section).
+GET_BAR_CONFIG (6)::
+ Gets the configuration (as JSON map) of the workspace bar with the
+ given ID. If no ID is provided, an array with all configured bar IDs is
+ returned instead.
So, a typical message could look like this:
--------------------------------------------------
Reply to the GET_OUTPUTS message.
GET_TREE (4)::
Reply to the GET_TREE message.
+GET_MARKS (5)::
+ Reply to the GET_MARKS message.
+GET_BAR_CONFIG (6)::
+ Reply to the GET_BAR_CONFIG message.
=== COMMAND reply
}
------------------------
+=== GET_MARKS reply
+
+The reply consists of a single array of strings for each container that has a
+mark. The order of that array is undefined. If more than one container has the
+same mark, it will be represented multiple times in the reply (the array
+contents are not unique).
+
+If no window has a mark the response will be the empty array [].
+
+=== GET_BAR_CONFIG reply
+
+This can be used by third-party workspace bars (especially i3bar, but others
+are free to implement compatible alternatives) to get the +bar+ block
+configuration from i3.
+
+Depending on the input, the reply is either:
+
+empty input::
+ An array of configured bar IDs
+Bar ID::
+ A JSON map containing the configuration for the specified bar.
+
+Each bar configuration has the following properties:
+
+id (string)::
+ The ID for this bar. Included in case you request multiple
+ configurations and want to differentiate the different replies.
+mode (string)::
+ Either +dock+ (the bar sets the dock window type) or +hide+ (the bar
+ does not show unless a specific key is pressed).
+position (string)::
+ Either +bottom+ or +top+ at the moment.
+status_command (string)::
+ Command which will be run to generate a statusline. Each line on stdout
+ of this command will be displayed in the bar. At the moment, no
+ formatting is supported.
+font (string)::
+ The font to use for text on the bar.
+workspace_buttons (boolean)::
+ Display workspace buttons or not? Defaults to true.
+verbose (boolean)::
+ Should the bar enable verbose output for debugging? Defaults to false.
+colors (map)::
+ Contains key/value pairs of colors. Each value is a color code in hex,
+ formatted #rrggbb (like in HTML).
+
+The following colors can be configured at the moment:
+
+background::
+ Background color of the bar.
+statusline::
+ Text color to be used for the statusline.
+focused_workspace_text/focused_workspace_bg::
+ Text color/background color for a workspace button when the workspace
+ has focus.
+active_workspace_text/active_workspace_bg::
+ Text color/background color for a workspace button when the workspace
+ is active (visible) on some output, but the focus is on another one.
+ You can only tell this apart from the focused workspace when you are
+ using multiple monitors.
+inactive_workspace_text/inactive_workspace_bg::
+ Text color/background color for a workspace button when the workspace
+ does not have focus and is not active (visible) on any output. This
+ will be the case for most workspaces.
+urgent_workspace_text/urgent_workspace_bar::
+ Text color/background color for workspaces which contain at least one
+ window with the urgency hint set.
+
+
+*Example of configured bars:*
+--------------
+["bar-bxuqzf"]
+--------------
+
+*Example of bar configuration:*
+--------------
+{
+ "id": "bar-bxuqzf",
+ "mode": "dock",
+ "position": "bottom",
+ "status_command": "i3status",
+ "font": "-misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1",
+ "workspace_buttons": true,
+ "verbose": false,
+ "colors": {
+ "background": "#c0c0c0",
+ "statusline": "#00ff00",
+ "focused_workspace_text": "#ffffff",
+ "focused_workspace_bg": "#000000"
+ }
+}
+--------------
== Events
# exit i3 (logs you out of your X session)\r
bindsym Mod1+Shift+e exit\r
\r
-# Start i3bar to display a workspace bar (plus the system information i3status\r
-# finds out, if available)\r
-exec i3status | i3bar -d</tt></pre>\r
+# display workspace buttons plus a statusline generated by i3status\r
+bar {\r
+ status_command i3status\r
+}</tt></pre>\r
</div></div>\r
</div>\r
<div class="sect2">\r
<div class="sect2">\r
<h3 id="_i3sock">7.1. I3SOCK</h3>\r
<div class="paragraph"><p>This variable overwrites the IPC socket path (placed in\r
-/tmp/i3-%u/ipc-socket.%p by default, where %u is replaced with your UNIX\r
-username and %p is replaced with i3’s PID). The IPC socket is used by external\r
-programs like i3-msg(1) or i3bar(1).</p></div>\r
+/tmp/i3-%u.XXXXXX/ipc-socket.%p by default, where %u is replaced with your UNIX\r
+username, %p is replaced with i3’s PID and XXXXXX is a string of random\r
+characters from the portable filename character set (see mkdtemp(3))). The IPC\r
+socket is used by external programs like i3-msg(1) or i3bar(1).</p></div>\r
</div>\r
</div>\r
</div>\r
<h1>IPC interface (interprocess communication)</h1>\r
<span id="author">Michael Stapelberg</span><br />\r
<span id="email"><tt><<a href="mailto:michael+i3@stapelberg.de">michael+i3@stapelberg.de</a>></tt></span><br />\r
-<span id="revdate">March 2010</span>\r
+<span id="revdate">October 2011</span>\r
<div id="toc">
<div id="toctitle">Table of Contents</div>
<noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
<div class="paragraph"><p>The method of choice for IPC in our case is a unix socket because it has very\r
little overhead on both sides and is usually available without headaches in\r
most languages. In the default configuration file, the ipc-socket gets created\r
-in <tt>/tmp/i3-%u/ipc-socket.%p</tt> where <tt>%u</tt> is your UNIX username and <tt>%p</tt> is the\r
-PID of i3.</p></div>\r
+in <tt>/tmp/i3-%u.XXXXXX/ipc-socket.%p</tt> where <tt>%u</tt> is your UNIX username, <tt>%p</tt> is\r
+the PID of i3 and XXXXXX is a string of random characters from the portable\r
+filename character set (see mkdtemp(3)). You can get the socketpath from i3 by\r
+calling <tt>i3 --get-socketpath</tt>.</p></div>\r
<div class="paragraph"><p>All i3 utilities, like <tt>i3-msg</tt> and <tt>i3-input</tt> will read the <tt>I3_SOCKET_PATH</tt>\r
X11 property, stored on the X11 root window.</p></div>\r
</div>\r
<div class="listingblock">\r
<div class="content">\r
<pre><tt>use IO::Socket::UNIX;\r
-my $sock = IO::Socket::UNIX->new(Peer => '/tmp/i3-ipc.sock');</tt></pre>\r
+chomp(my $path = qx(i3 --get-socketpath));\r
+my $sock = IO::Socket::UNIX->new(Peer => $path);</tt></pre>\r
</div></div>\r
</div>\r
</div>\r
section).\r
</p>\r
</dd>\r
+<dt class="hdlist1">\r
+GET_MARKS (5)\r
+</dt>\r
+<dd>\r
+<p>\r
+ Gets a list of marks (identifiers for containers to easily jump to them\r
+ later). The reply will be a JSON-encoded list of window marks (see\r
+ reply section).\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+GET_BAR_CONFIG (6)\r
+</dt>\r
+<dd>\r
+<p>\r
+ Gets the configuration (as JSON map) of the workspace bar with the\r
+ given ID. If no ID is provided, an array with all configured bar IDs is\r
+ returned instead.\r
+</p>\r
+</dd>\r
</dl></div>\r
<div class="paragraph"><p>So, a typical message could look like this:</p></div>\r
<div class="listingblock">\r
Reply to the GET_TREE message.\r
</p>\r
</dd>\r
+<dt class="hdlist1">\r
+GET_MARKS (5)\r
+</dt>\r
+<dd>\r
+<p>\r
+ Reply to the GET_MARKS message.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+GET_BAR_CONFIG (6)\r
+</dt>\r
+<dd>\r
+<p>\r
+ Reply to the GET_BAR_CONFIG message.\r
+</p>\r
+</dd>\r
</dl></div>\r
</div>\r
<div class="sect2">\r
}</tt></pre>\r
</div></div>\r
</div>\r
+<div class="sect2">\r
+<h3 id="_get_marks_reply">3.7. GET_MARKS reply</h3>\r
+<div class="paragraph"><p>The reply consists of a single array of strings for each container that has a\r
+mark. The order of that array is undefined. If more than one container has the\r
+same mark, it will be represented multiple times in the reply (the array\r
+contents are not unique).</p></div>\r
+<div class="paragraph"><p>If no window has a mark the response will be the empty array [].</p></div>\r
+</div>\r
+<div class="sect2">\r
+<h3 id="_get_bar_config_reply">3.8. GET_BAR_CONFIG reply</h3>\r
+<div class="paragraph"><p>This can be used by third-party workspace bars (especially i3bar, but others\r
+are free to implement compatible alternatives) to get the <tt>bar</tt> block\r
+configuration from i3.</p></div>\r
+<div class="paragraph"><p>Depending on the input, the reply is either:</p></div>\r
+<div class="dlist"><dl>\r
+<dt class="hdlist1">\r
+empty input\r
+</dt>\r
+<dd>\r
+<p>\r
+ An array of configured bar IDs\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+Bar ID\r
+</dt>\r
+<dd>\r
+<p>\r
+ A JSON map containing the configuration for the specified bar.\r
+</p>\r
+</dd>\r
+</dl></div>\r
+<div class="paragraph"><p>Each bar configuration has the following properties:</p></div>\r
+<div class="dlist"><dl>\r
+<dt class="hdlist1">\r
+id (string)\r
+</dt>\r
+<dd>\r
+<p>\r
+ The ID for this bar. Included in case you request multiple\r
+ configurations and want to differentiate the different replies.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+mode (string)\r
+</dt>\r
+<dd>\r
+<p>\r
+ Either <tt>dock</tt> (the bar sets the dock window type) or <tt>hide</tt> (the bar\r
+ does not show unless a specific key is pressed).\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+position (string)\r
+</dt>\r
+<dd>\r
+<p>\r
+ Either <tt>bottom</tt> or <tt>top</tt> at the moment.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+status_command (string)\r
+</dt>\r
+<dd>\r
+<p>\r
+ Command which will be run to generate a statusline. Each line on stdout\r
+ of this command will be displayed in the bar. At the moment, no\r
+ formatting is supported.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+font (string)\r
+</dt>\r
+<dd>\r
+<p>\r
+ The font to use for text on the bar.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+workspace_buttons (boolean)\r
+</dt>\r
+<dd>\r
+<p>\r
+ Display workspace buttons or not? Defaults to true.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+verbose (boolean)\r
+</dt>\r
+<dd>\r
+<p>\r
+ Should the bar enable verbose output for debugging? Defaults to false.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+colors (map)\r
+</dt>\r
+<dd>\r
+<p>\r
+ Contains key/value pairs of colors. Each value is a color code in hex,\r
+ formatted #rrggbb (like in HTML).\r
+</p>\r
+</dd>\r
+</dl></div>\r
+<div class="paragraph"><p>The following colors can be configured at the moment:</p></div>\r
+<div class="dlist"><dl>\r
+<dt class="hdlist1">\r
+background\r
+</dt>\r
+<dd>\r
+<p>\r
+ Background color of the bar.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+statusline\r
+</dt>\r
+<dd>\r
+<p>\r
+ Text color to be used for the statusline.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+focused_workspace_text/focused_workspace_bg\r
+</dt>\r
+<dd>\r
+<p>\r
+ Text color/background color for a workspace button when the workspace\r
+ has focus.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+active_workspace_text/active_workspace_bg\r
+</dt>\r
+<dd>\r
+<p>\r
+ Text color/background color for a workspace button when the workspace\r
+ is active (visible) on some output, but the focus is on another one.\r
+ You can only tell this apart from the focused workspace when you are\r
+ using multiple monitors.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+inactive_workspace_text/inactive_workspace_bg\r
+</dt>\r
+<dd>\r
+<p>\r
+ Text color/background color for a workspace button when the workspace\r
+ does not have focus and is not active (visible) on any output. This\r
+ will be the case for most workspaces.\r
+</p>\r
+</dd>\r
+<dt class="hdlist1">\r
+urgent_workspace_text/urgent_workspace_bar\r
+</dt>\r
+<dd>\r
+<p>\r
+ Text color/background color for workspaces which contain at least one\r
+ window with the urgency hint set.\r
+</p>\r
+</dd>\r
+</dl></div>\r
+<div class="paragraph"><p><strong>Example of configured bars:</strong></p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>["bar-bxuqzf"]</tt></pre>\r
+</div></div>\r
+<div class="paragraph"><p><strong>Example of bar configuration:</strong></p></div>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>{\r
+ "id": "bar-bxuqzf",\r
+ "mode": "dock",\r
+ "position": "bottom",\r
+ "status_command": "i3status",\r
+ "font": "-misc-fixed-medium-r-normal--13-120-75-75-C-70-iso10646-1",\r
+ "workspace_buttons": true,\r
+ "verbose": false,\r
+ "colors": {\r
+ "background": "#c0c0c0",\r
+ "statusline": "#00ff00",\r
+ "focused_workspace_text": "#ffffff",\r
+ "focused_workspace_bg": "#000000"\r
+ }\r
+}</tt></pre>\r
+</div></div>\r
+</div>\r
</div>\r
</div>\r
<div class="sect1">\r
--- /dev/null
+
+ ┌──────────────────────────────┐
+ │ Release notes for i3 v4.1.2 │
+ └──────────────────────────────┘
+
+This is the second minor release of i3 v4.1. It is a bugfix release and
+considered stable. All users of i3 v4.1.1 are strongly encouraged to upgrade.
+
+i3 developers will be present at FOSDEM in Brussels.
+Please get in touch and have a nice chat with us :).
+
+
+ ┌────────────────────────────┐
+ │ Changes in v4.1.2 │
+ └────────────────────────────┘
+
+ • Bugfix: Don’t lose focus on fullscreen windows when another window gets
+ moved to that workspace
+ • Bugfix: Open new windows in the correct place when assignments match
+ • Bugfix: Fix assignments of floating windows to (yet) unused workspaces
+ • Bugfix: Either use SetInputFocus *or* send WM_TAKE_FOCUS, not both
+ • Bugfix: Respect WM_HINTS.input for WM_TAKE_FOCUS clients
+ • Bugfix: Setup the _NET_SUPPORTING_WM_CHECK atom in a standards-compliant way
+ • Bugfix: Only ignore EnterNotify events after UnmapNotifies from managed windows
+ • Bugfix: Force a new sequence number after UnmapNotify
+ • Bugfix: Position floating windows exactly where their geometry specified
+ • Bugfix: Fix coordinates when the rect of an output changes
+
+ ┌────────────────────────────┐
+ │ Thanks! │
+ └────────────────────────────┘
+
+Thanks for testing, bugfixes, discussions and everything I forgot go out to:
+
+ B-Con, David Coppa, Don, Paul, rami, zeus
+
+-- Michael Stapelberg, 2012-01-27
--- /dev/null
+-----BEGIN PGP SIGNATURE-----
+Version: GnuPG v1.4.11 (GNU/Linux)
+
+iQIcBAABCAAGBQJPIvpqAAoJEE5xYO1KyO4drGUQAIb497YrMh7UP8x+70XFBI/q
+aUaGCxur0IEGart3geQQ2aCm0SeHyhmeQI7qRkzMrNTXZwjiapCfkjzbumUq001Y
+UXgL1hhyDw1ync/opfjwCAYauHcgs0YhvUHwGYduKHF7ni2JuW0ezaKIyDRquwjV
+bRu/0iya3SkonsT8rZJMiFUa1vfnznuktu5CUR4PhPzlEQ2Tk9iLFSDAGTZjIsCT
+yL3FW0zAAHDjFGhyS1uPRGFUa6g0QQ4/tGygLuai5BQ4kLqwzg0yP9v5cpSdYoEN
+BJZKfvqZvHiZFUBmR2KusXsqpFUCBrgF5Q4OuGIsvtk80lHpJU1jCPiH5X/EvNsJ
+dNqB55NTcZ3u1JlsrTqmRj7C3wVA6ZnRRxp2nUKplNpI6LEYj9pD+50t7RDvW89E
+vrZNPGBrNDMUhyvDxv2imQqEEV2MTRq8ATI75dmBAZ1CWdLsxBETpV2CQeQ7Ep71
+OyMzKcmPy8gMOltNdEvwfF0KN+R4Tw69dR/zpAuG6aYyDRJv52y6xCv0I6kkEx7x
+Cr3Jmif35vuFQpg083cGXODk+sNgfiHJTO7bOQ/TMvCpEEmFie/LWMSjJegVvb5y
+mmq+KPSK7Ch2QYVhK3fh5Z8DfCR9ygUfVkxXZEr744K8OFA3Db9RGARtdnAKnYpn
+TmF8p1Vcqv2fufhYxl3+
+=EntO
+-----END PGP SIGNATURE-----
<h2>Downloads</h2>
<p>
- The current stable version is 4.1.1.
+ The current stable version is 4.1.2.
</p>
<p>
</thead>
<tbody>
+ <tr>
+ <td>4.1.2</td>
+ <td><a href="/downloads/i3-4.1.2.tar.bz2">i3-4.1.2.tar.bz2</a></td>
+ <td>550 KiB</td>
+ <td><a href="/downloads/i3-4.1.2.tar.bz2.asc">signature</a></td>
+ <td>2012-01-27</td>
+ <td><a href="/downloads/RELEASE-NOTES-4.1.2.txt">release notes</a></td>
+ </tr>
+
<tr>
<td>4.1.1</td>
<td><a href="/downloads/i3-4.1.1.tar.bz2">i3-4.1.1.tar.bz2</a></td>
<a href="/downloads">
<span style="font-weight: bold; color: #3A8ECD; margin-right: .5em">➡</span>
Download the latest version
- <span style="margin-left: 2em; color: #c0c0c0">4.1.1</span>
+ <span style="margin-left: 2em; color: #c0c0c0">4.1.2</span>
</a>
</div>
</div>
projects / i3 / i3.github.io / commitdiff