<p>
The goal of py3status is to fill this gap by allowing users to simply extend
their i3bar while preserving their current i3status configuration. The main idea
-is to rely on i3status' strengths without adding any configuration on the user's
-side. py3status is thus a wrapper script for i3status and you can
-<a href="https://github.com/ultrabug/py3status/wiki"> read more on the wiki</a>.
+is to rely on i3status' strength without adding any configuration on the user's
+side. py3status is thus a wrapper script for i3status and its configuration as
+explained <a href="https://github.com/ultrabug/py3status/tree/master/doc">
+in the documentation</a>.
</p>
-<h2>Requirements</h2>
+<h2>Usage</h2>
<p>
-To achieve this, py3status uses the <a
-href="http://i3wm.org/docs/i3bar-protocol.html">i3bar protocol</a> so your
-i3status.conf should specify this as its output_format.
+Using py3status is easy, no need to multi-pipe your scripts after i3status.
+Instead just replace <i>i3status</i> in your current <b>status_command</b> by
+ <i>py3status</i>.
+For example, if your current status_command in your i3 config file resides in
+~/.i3/i3status.conf, you would change your i3 config to this:
</p>
-<pre><tt>general {
- output_format = "i3bar"
-}</tt></pre>
+<pre><tt>status_command py3status -c ~/.i3/i3status.conf</tt></pre>
-<h2>Usage</h2>
+<h2>Handle i3bar click events from your i3status.conf</h2>
<p>
-Using py3status is easy, no need to multi-pipe your scripts after i3status.
-Instead, just replace i3status in your current status_command by py3status.
-For example, if you're using your own i3status.conf, you need to change your
-i3 config file with:
+Py3status (since v2) is also wrapping and extending your i3status.conf and
+allows you directly handle all the i3bar click events on any of your configured
+modules whether they are i3status modules or py3status modules.
</p>
-<pre><tt>status_command py3status -c ~/.i3/i3status.conf</tt></pre>
+<p>
+To do so, all you have to do is add a new configuration parameter named
+<b>on_click [button number]</b> to your module config and py3status will then
+execute the given i3 command (using i3-msg). This means you can run simple
+tasks like executing a program or execute any other i3 specific command.
+</p>
+<p>Some examples below from i3status.conf:</p>
+
+<pre><tt>
+# reload the i3 config when I left click on the i3status time module
+# and restart i3 when I middle click on it
+time {
+ on_click 1 = "reload"
+ on_click 2 = "restart"
+}
+
+# run wicd-gtk GUI when I left click on the i3status ethernet module
+# and kill it when I right click on it
+ethernet eth0 {
+ # if you use %speed, i3status requires root privileges
+ format_up = "E: %ip"
+ format_down = ""
+ on_click 1 = "exec wicd-gtk"
+ on_click 3 = "exec killall wicd-gtk"
+}
+
+# run thunar when I left click on the / disk info module
+disk / {
+ format = "/ %free"
+ on_click 1 = "exec thunar /"
+}
+
+# open an URL on firefox when I left click on the py3status weather_yahoo module
+weather_yahoo paris {
+ cache_timeout = 7200
+ woeid = 615702
+ forecast_days = 2
+ request_timeout = 10
+ on_click 1 = "exec firefox-bin http://www.meteo.fr"
+}
+</tt></pre>
+
+<h2>Use py3status modules on your i3bar</h2>
+
+<p>
+Py3status also comes with some configurable modules you can load and
+configure directly from your i3status.conf just like any other i3status module.
+<a
+href="https://github.com/ultrabug/py3status/tree/master/py3status/modules">You
+can see the list of the modules and their configuration parameters here.</a>
+</p>
+
+<p>
+To load a py3status module you just have to list it like any other i3status
+module using the <b>order +=</b> parameter. For example you could insert and
+load the imap module like this:
+</p>
+
+<pre><tt>
+order += "disk /home"
+order += "disk /"
+order += "imap"
+order += "time"
+</tt></pre>
+
+<p>And then you could configure it like this:</p>
+
+<pre><tt>
+# configure the py3status imap module
+# and run thunderbird when I left click on it
+imap {
+ cache_timeout = 60
+ imap_server = 'imap.myprovider.com'
+ mailbox = 'INBOX'
+ name = 'Mail'
+ password = 'coconut'
+ port = '993'
+ user = 'mylogin'
+ on_click 1 = "exec thunderbird"
+}
+</tt></pre>
+
+<h2>Group modules to save space on your i3bar</h2>
+
+<p>
+The <b>group</b> module allows you to group several modules together.
+Only one of the modules are displayed at a time. The displayed module can either
+be cycled through automatically or by user action (mouse scroll by default).
+</p>
+
+<p>Example usage:</p>
+
+<pre><tt>
+order += "group tz"
+
+# cycle through different timezone hours every 10s
+group tz {
+ cycle = 10
+ format = "{output}"
+
+ tztime la {
+ format = "LA %H:%M"
+ timezone = "America/Los_Angeles"
+ }
+
+ tztime ny {
+ format = "NY %H:%M"
+ timezone = "America/New_York"
+ }
+
+ tztime du {
+ format = "DU %H:%M"
+ timezone = "Asia/Dubai"
+ }
+}
+</tt></pre>
-<h2>Display your own stuff</h2>
+<h2>Write your own modules to display your own stuff</h2>
<p>
-py3status features a simple and straightforward plugin system which you can use
+Py3status features a simple and straightforward module system which you can use
to get your own output displayed on your i3bar. You can read more and view some
examples <a
-href="https://github.com/ultrabug/py3status/wiki/Write-your-own-modules"> on the
-wiki</a>.
+href="https://github.com/ultrabug/py3status/tree/master/doc#writing_custom_modules">
+in the documentation</a>.
</p>
<h2>Documentation</h2>
<p>
You can read the full and up to date documentation on the <a
-href="https://github.com/ultrabug/py3status">py3status home page</a>.
+href="https://github.com/ultrabug/py3status/tree/master/doc">py3status docs</a>.
</p>