--- /dev/null
+---
+layout: default
+title: Docs
+group: Docs
+---
+<div id="content" class="usergen">
+<h1>User-contributed article: enhanced and extensible i3bar with py3status</h1>
+
+<p>
+In the i3 documentation, the recommended tool for <a
+href="http://i3wm.org/docs/userguide.html#_displaying_a_status_line">displaying
+a status line is to use i3status</a> combined with i3bar.
+</p>
+
+<p>
+While i3status is very efficient at what it does, it is by design limited to
+a few modules and does not allow you to inject your own scripts output on your
+i3bar. This is said pretty clearly on the i3status man page:
+</p>
+
+<pre><tt>In i3status, we don’t want to implement process management again.
+Therefore, there is no module to run arbitrary scripts or commands.
+Instead, you should use your shell.</tt></pre>
+
+<h2>Introducing py3status</h2>
+
+<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' 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>Usage</h2>
+
+<p>
+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>status_command py3status -c ~/.i3/i3status.conf</tt></pre>
+
+<h2>Handle i3bar click events from your i3status.conf</h2>
+
+<p>
+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>
+
+<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>Write your own modules to display your own stuff</h2>
+
+<p>
+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/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/tree/master/doc">py3status docs</a>.
+</p>
projects / i3 / i3.github.io / blobdiff