git.sur5r.net Git - i3/i3.github.io/blob - docs/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="https://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, fairly
  17 limited to a few modules and file ouput which does not give the flexibility to
  18 users to easily add anything they want to their bar.
  19 </p>
  20
  21 <p>
  22 This is said pretty clearly on the i3status man page:
  23 </p>
  24 <pre><tt>*EXTERNAL SCRIPTS/PROGRAMS WITH I3STATUS
  25
  26     In i3status, we don’t want to implement process management again.
  27     Therefore, there is no module to run arbitrary scripts or commands.
  28     Instead, you should use your shell.
  29 </tt></pre>
  30
  31 <h2>Introducing py3status</h2>
  32
  33 <p>
  34 The goal of py3status is to fill this gap by allowing users to simply extend
  35 their i3bar <b>while preserving their current i3status configuration</b>.
  36 The main idea is to rely on i3status' strength without adding any configuration
  37 on the user's side. py3status is thus a wrapper script for i3status and its
  38 configuration as explained in the documentation below.
  39 This should be said that py3status is much more than just a wrapper script.
  40 </p>
  41
  42 <h2>Documentation</h2>
  43
  44 <p>View the full documentation now or bookmark it for later viewing:</p>
  45 <ul>
  46 <li>
  47     <a href="https://py3status.readthedocs.io/en/latest">Read the Docs</a>
  48 </li>
  49 <li>
  50     <a href="https://github.com/ultrabug/py3status/tree/master/doc">Github</a>
  51 </li>
  52 </ul>
  53
  54 <h2>Using py3status</h2>
  55
  56 <p>Using py3status has never been so easy. Update your i3 config with this and
  57 you're done:</p>
  58 <pre><tt>
  59 bar {
  60     status_command py3status
  61 }
  62 </tt></pre>
  63
  64 <p>
  65 In other words, just replace <i>i3status</i> in your current
  66 <b>status_command</b> by <i>py3status</i>.
  67 </p>
  68
  69 <p>Py3status will look for status config file in this order.</p>
  70 <pre><tt>
  71 1    ~/.config/py3status/config
  72 2    ~/.config/i3status/config
  73 3    ~/.config/i3/i3status.conf
  74 4    ~/.i3status.conf
  75 5    ~/.i3/i3status.conf
  76 6    /etc/xdg/i3status/config
  77 7    /etc/i3status.conf
  78 </tt></pre>
  79
  80 <p>Alternatively, you can start from scratch with an empty status config.</p>
  81 <pre><tt>
  82 bar {
  83     status_command py3status -c ~/.config/py3status/config
  84 }
  85 </tt></pre>
  86
  87 <p>Learn more about how to configure py3status on the
  88 <a href="https://py3status.readthedocs.io/en/latest/configuration.html">
  89 configuration documentation</a>
  90 </p>
  91
  92 <h2>Using py3status modules</h2>
  93
  94 <p>Like i3status, py3status comes with modules (but a lot of them!).</p>
  95 <p>Learn more about the modules provided by py3status on the
  96 <a href="https://py3status.readthedocs.io/en/latest/modules.html">modules
  97 documentation</a>
  98 </p>
  99
 100 <p>
 101 Like i3status, we can add and configure the modules the same way... usually in
 102 the status config.</p>
 103
 104 <p>An excerpt from <span class="box">man 1 i3status</span>.</p>
 105 <pre><tt>CONFIGURATION
 106
 107     The basic idea of i3status is that you can specify which "modules" should be
 108     used (the order directive).
 109     You can then configure each module with its own section. For every module,
 110     you can specify the output format.
 111 </tt></pre>
 112
 113 <p>A skeleton reference.</p>
 114 <pre><tt>
 115 order += "module_name"
 116 module_name {
 117     config_name = "..."
 118 }
 119 </tt></pre>
 120
 121 <p>An example of using <span class="box">imap</span> module.</p>
 122 <pre><tt>
 123 order += "battery 0"
 124 order += "disk /"
 125 order += "imap"    <----
 126 order += "time"
 127 </tt></pre>
 128 <pre><tt>
 129 # add imap settings and open xterm with mutt on left-click
 130 imap {
 131     user = "alex"
 132     password = "ilovebugs"
 133     port = "993"
 134     server = "imap.mybugprovider.com"
 135
 136     on_click 1 = "exec xterm -e mutt"
 137 }
 138 </tt></pre>
 139
 140 <h2>Clicking the modules</h2>
 141
 142 <p>
 143 Starting with <span class="box">version 2.0</span>, py3status allows the mouse
 144 click events from the modules to be bound as options in the status config where
 145 the users can configure what to do when they received the click events.
 146 </p>
 147 <p>It is possible to run commands, scripts, or programs with a click.</p>
 148 <p>You can place the configuration parameter
 149 <span class="box">on_click [button number] = "[command]"</span> in the module
 150 section.
 151
 152 Py3status will run the <span class="box">command</span> using
 153 <span class="box">i3-msg</span> when the module's click event matches the
 154 configured module section's click <span class="box">event</span>.</p>
 155
 156 <p>Quick reference:</p>
 157 <pre><tt>
 158 on_click [button number] = "[command]"
 159 on_click 1 = "exec firefox"    ---->    i3-msg "exec firefox"
 160 </tt></pre>
 161
 162 <p>Click events buttons reference:</p>
 163 <pre><tt>
 164 1 left button
 165 2 middle button
 166 3 right button
 167 4 up scroll
 168 5 down scroll
 169 </tt></pre>
 170
 171 <p>Examples of using <span class="box">on_click</span> config:</p>
 172 <pre><tt>
 173 # reload i3 on left-click
 174 # restart i3 on middle-click
 175 time {
 176     on_click 1 = "reload"
 177     on_click 2 = "restart"
 178 }
 179
 180 # open wicd-gtk on left-click
 181 # kill wicd-gtk on right-click
 182 ethernet eth0 {
 183     on_click 1 = "exec wicd-gtk"
 184     on_click 3 = "exec killall wicd-gtk"
 185 }
 186
 187 # open thunar on left-click
 188 disk {
 189     on_click 1 = "exec thunar"
 190 }
 191
 192 # open firefox with an URL on left-click
 193 weather_yahoo paris {
 194     on_click 1 = "exec firefox http://www.my-favorite-weather-site.com/
 195 }
 196 </tt></pre>
 197
 198 <h2>Grouping the modules</h2>
 199
 200 <p>
 201 The <span class="box">group</span> module allows you to group several modules
 202 together to save space. Only one of the them will be displayed at a time.
 203 </p>
 204 <p>
 205 The modules of a <span class="box">group</span> can either be cycled through
 206 automatically or by user action (mouse scroll by default).
 207 </p>
 208
 209 <p>An example of using the <span class="box">group</span> module with 3
 210 different <span class="box">tztime</span> modules:</p>
 211 <pre><tt>
 212 order += "group tz"
 213
 214 # cycle through different timezone hours every 10s
 215 group tz {
 216     cycle = 10
 217     format = "{output}"
 218
 219     tztime la {
 220         format = "LA %H:%M"
 221         timezone = "America/Los_Angeles"
 222     }
 223
 224     tztime ny {
 225         format = "NY %H:%M"
 226         timezone = "America/New_York"
 227     }
 228
 229     tztime du {
 230         format = "DU %H:%M"
 231         timezone = "Asia/Dubai"
 232     }
 233 }
 234 </tt></pre>
 235
 236 <h2>Writing new modules for py3status</h2>
 237
 238 <ul>
 239 <li>py3status utilizes an easy-to-use and straightforward system for its
 240 modules.</li>
 241 <li>py3status contains an excellent set of useful functions to make writing
 242 things easier.</li>
 243 <li>py3status continues to grow healthy with well written documentation on the
 244 modules, on the functions and parameters, on making new modules, and many more.
 245 </li>
 246 </ul>
 247
 248 <p>Learn how to
 249 <a href="https://py3status.readthedocs.io/en/latest/writing_modules.html">write
 250 (and contribute please!) your own modules!</a></p>
 251
 252
 253 </div>