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