git.sur5r.net Git - i3/i3.github.io/blob - docs/4.13/user-contributed/py3status.html

   1 ---
   2 layout: default
   3 title: Docs
   4 group: Docs
   5 ---
   6 <div id="content" class="usergen">
   7 <h1>User-contributed article: enhanced and extensible i3bar with py3status</h1>
   8
   9 <p>
  10 In the i3 documentation, the recommended tool for <a
  11 href="http://i3wm.org/docs/userguide.html#_displaying_a_status_line">displaying
  12 a status line is to use i3status</a> combined with i3bar.
  13 </p>
  14
  15 <p>
  16 While i3status is very efficient at what it does, it is by design limited to
  17 a few modules and does not allow you to inject your own scripts output on your
  18 i3bar. This is said pretty clearly on the i3status man page:
  19 </p>
  20
  21 <pre><tt>In i3status, we don’t want to implement process management again.
  22 Therefore, there is no module to run arbitrary scripts or commands.
  23 Instead, you should use your shell.</tt></pre>
  24
  25 <h2>Introducing py3status</h2>
  26
  27 <p>
  28 The goal of py3status is to fill this gap by allowing users to simply extend
  29 their i3bar while preserving their current i3status configuration. The main idea
  30 is to rely on i3status' strength without adding any configuration on the user's
  31 side. py3status is thus a wrapper script for i3status and its configuration as
  32 explained <a href="https://github.com/ultrabug/py3status/tree/master/doc">
  33 in the documentation</a>.
  34 </p>
  35
  36 <h2>Usage</h2>
  37
  38 <p>
  39 Using py3status is easy, no need to multi-pipe your scripts after i3status.
  40 Instead just replace <i>i3status</i> in your current <b>status_command</b> by
  41  <i>py3status</i>.
  42 For example, if your current status_command in your i3 config file resides in
  43 ~/.i3/i3status.conf, you would change your i3 config to this:
  44 </p>
  45
  46 <pre><tt>status_command py3status -c ~/.i3/i3status.conf</tt></pre>
  47
  48 <h2>Handle i3bar click events from your i3status.conf</h2>
  49
  50 <p>
  51 Py3status (since v2) is also wrapping and extending your i3status.conf and
  52 allows you directly handle all the i3bar click events on any of your configured
  53 modules whether they are i3status modules or py3status modules.
  54 </p>
  55
  56 <p>
  57 To do so, all you have to do is add a new configuration parameter named
  58 <b>on_click [button number]</b> to your module config and py3status will then
  59 execute the given i3 command (using i3-msg). This means you can run simple
  60 tasks like executing a program or execute any other i3 specific command.
  61 </p>
  62 <p>Some examples below from i3status.conf:</p>
  63
  64 <pre><tt>
  65 # reload the i3 config when I left click on the i3status time module
  66 # and restart i3 when I middle click on it
  67 time {
  68     on_click 1 = "reload"
  69     on_click 2 = "restart"
  70 }
  71
  72 # run wicd-gtk GUI when I left click on the i3status ethernet module
  73 # and kill it when I right click on it
  74 ethernet eth0 {
  75     # if you use %speed, i3status requires root privileges
  76     format_up = "E: %ip"
  77     format_down = ""
  78     on_click 1 = "exec wicd-gtk"
  79     on_click 3 = "exec killall wicd-gtk"
  80 }
  81
  82 # run thunar when I left click on the / disk info module
  83 disk / {
  84     format = "/ %free"
  85     on_click 1 = "exec thunar /"
  86 }
  87
  88 # open an URL on firefox when I left click on the py3status weather_yahoo module
  89 weather_yahoo paris {
  90     cache_timeout = 7200
  91     woeid = 615702
  92     forecast_days = 2
  93     request_timeout = 10
  94     on_click 1 = "exec firefox-bin http://www.meteo.fr"
  95 }
  96 </tt></pre>
  97
  98 <h2>Use py3status modules on your i3bar</h2>
  99
 100 <p>
 101 Py3status also comes with some configurable modules you can load and
 102 configure directly from your i3status.conf just like any other i3status module.
 103 <a
 104 href="https://github.com/ultrabug/py3status/tree/master/py3status/modules">You
 105 can see the list of the modules and their configuration parameters here.</a>
 106 </p>
 107
 108 <p>
 109 To load a py3status module you just have to list it like any other i3status
 110 module using the <b>order +=</b> parameter. For example you could insert and
 111 load the imap module like this:
 112 </p>
 113
 114 <pre><tt>
 115 order += "disk /home"
 116 order += "disk /"
 117 order += "imap"
 118 order += "time"
 119 </tt></pre>
 120
 121 <p>And then you could configure it like this:</p>
 122
 123 <pre><tt>
 124 # configure the py3status imap module
 125 # and run thunderbird when I left click on it
 126 imap {
 127     cache_timeout = 60
 128     imap_server = 'imap.myprovider.com'
 129     mailbox = 'INBOX'
 130     name = 'Mail'
 131     password = 'coconut'
 132     port = '993'
 133     user = 'mylogin'
 134     on_click 1 = "exec thunderbird"
 135 }
 136 </tt></pre>
 137
 138 <h2>Group modules to save space on your i3bar</h2>
 139
 140 <p>
 141 The <b>group</b> module allows you to group several modules together.
 142 Only one of the modules are displayed at a time. The displayed module can either
 143 be cycled through automatically or by user action (mouse scroll by default).
 144 </p>
 145
 146 <p>Example usage:</p>
 147
 148 <pre><tt>
 149 order += "group tz"
 150
 151 # cycle through different timezone hours every 10s
 152 group tz {
 153     cycle = 10
 154     format = "{output}"
 155
 156     tztime la {
 157         format = "LA %H:%M"
 158         timezone = "America/Los_Angeles"
 159     }
 160
 161     tztime ny {
 162         format = "NY %H:%M"
 163         timezone = "America/New_York"
 164     }
 165
 166     tztime du {
 167         format = "DU %H:%M"
 168         timezone = "Asia/Dubai"
 169     }
 170 }
 171 </tt></pre>
 172
 173 <h2>Write your own modules to display your own stuff</h2>
 174
 175 <p>
 176 Py3status features a simple and straightforward module system which you can use
 177 to get your own output displayed on your i3bar. You can read more and view some
 178 examples <a
 179 href="https://github.com/ultrabug/py3status/tree/master/doc#writing_custom_modules">
 180 in the documentation</a>.
 181 </p>
 182
 183 <h2>Documentation</h2>
 184
 185 <p>
 186 You can read the full and up to date documentation on the <a
 187 href="https://github.com/ultrabug/py3status/tree/master/doc">py3status docs</a>.
 188 </p>