X-Git-Url: https://git.sur5r.net/?p=i3%2Fi3.github.io;a=blobdiff_plain;f=docs%2Fuser-contributed%2Fpy3status.html;fp=docs%2Fuser-contributed%2Fpy3status.html;h=44c6f30dacfc3c1143ae95d99fae777ae1656c0f;hp=cb84b58adc5234fc6b37a77efbfcc21f6fc1c563;hb=ec9d7e608aa0b5877b21a8af3f6011153d0d7c7c;hpb=a46029331047cd4e7b9225228e61b3378bd3c3af diff --git a/docs/user-contributed/py3status.html b/docs/user-contributed/py3status.html index cb84b58..44c6f30 100644 --- a/docs/user-contributed/py3status.html +++ b/docs/user-contributed/py3status.html @@ -8,143 +8,203 @@ group: Docs
In the i3 documentation, the recommended tool for displaying +href="https://i3wm.org/docs/userguide.html#_displaying_a_status_line">displaying a status line is to use i3status combined with i3bar.
-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: +While i3status is very efficient at what it does, it is, by design, fairly +limited to a few modules and does not allow not allow the users to add anything +to the i3bar. This was said pretty clearly on the i3status man page:
-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.+
*EXTERNAL SCRIPTS/PROGRAMS WITH I3STATUS + + 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. +
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 -in the documentation. +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 in the documentation below. +This should be said that py3status is much more than just a wrapper script.
--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 your current status_command in your i3 config file resides in -~/.i3/i3status.conf, you would change your i3 config to this: -
+View the full documentation now or bookmark it for later viewing:
+status_command py3status -c ~/.i3/i3status.conf+
Using py3status has never been so easy. Update your i3 config with this and +you're done:
++bar { + status_command py3status +} +
-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. +In other words, just replace i3status in your current +status_command by py3status.
--To do so, all you have to do is add a new configuration parameter named -on_click [button number] 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. -
-Some examples below from i3status.conf:
+Py3status will look for status config file in this order.
++1 ~/.config/py3status/config +2 ~/.config/i3status/config +3 ~/.config/i3/i3status.conf +4 ~/.i3status.conf +5 ~/.i3/i3status.conf +6 /etc/xdg/i3status/config +7 /etc/i3status.conf ++
Alternatively, you can start from scratch with an empty status config.
-# 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" +bar { + status_command py3status -c ~/.config/py3status/config } +-# 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" -} +
Learn more about how to configure py3status on the + +configuration documentation +
+ +Like i3status, py3status comes with modules (but a lot of them!).
+Learn more about the modules provided by py3status on the +modules +documentation +
+ ++Like i3status, we can add and configure the modules the same way... usually in +the status config.
-# run thunar when I left click on the / disk info module -disk / { - format = "/ %free" - on_click 1 = "exec thunar /" +An excerpt from man 1 i3status.
+CONFIGURATION + + The basic idea of i3status is that you can specify which "modules" should be + used (the order directive). + You can then configure each module with its own section. For every module, + you can specify the output format. ++ +
A skeleton reference.
++order += "module_name" +module_name { + config_name = "..." } +-# 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" +
An example of using imap module.
++order += "battery 0" +order += "disk /" +order += "imap" <---- +order += "time" ++
+# add imap settings and open xterm with mutt on left-click +imap { + user = "alex" + password = "ilovebugs" + port = "993" + server = "imap.mybugprovider.com" + + on_click 1 = "exec xterm -e mutt" }-
-Py3status also comes with some configurable modules you can load and -configure directly from your i3status.conf just like any other i3status module. -You -can see the list of the modules and their configuration parameters here. +Starting with version 2.0, py3status allows the mouse +click events from the modules to be bound as options in the status config where +the users can configure what to do when they received the click events.
+It is possible to run commands, scripts, or programs with a click.
+You can place the configuration parameter +on_click [button number] = "[command]" in the module +section. -
-To load a py3status module you just have to list it like any other i3status -module using the order += parameter. For example you could insert and -load the imap module like this: -
+Py3status will run the command using +i3-msg when the module's click event matches the +configured module section's click event. +Quick reference:
-order += "disk /home" -order += "disk /" -order += "imap" -order += "time" +on_click [button number] = "[command]" +on_click 1 = "exec firefox" ----> i3-msg "exec firefox"-
And then you could configure it like this:
+Click events buttons reference:
++1 left button +2 middle button +3 right button +4 up scroll +5 down scroll ++
Examples of using on_click config:
-# 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" +# reload i3 on left-click +# restart i3 on middle-click +time { + on_click 1 = "reload" + on_click 2 = "restart" +} + +# open wicd-gtk on left-click +# kill wicd-gtk on right-click +ethernet eth0 { + on_click 1 = "exec wicd-gtk" + on_click 3 = "exec killall wicd-gtk" +} + +# open thunar on left-click +disk { + on_click 1 = "exec thunar" +} + +# open firefox with an URL on left-click +weather_yahoo paris { + on_click 1 = "exec firefox http://www.my-favorite-weather-site.com/ }-
-The group 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). +The group module allows you to group several modules +together to save space. Only one of the them will be displayed at a time. +
++The modules of a group can either be cycled through +automatically or by user action (mouse scroll by default).
-Example usage:
- +An example of using the group module with 3 +different tztime modules:
order += "group tz" @@ -170,19 +230,21 @@ group tz { }-
-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 -in the documentation. -
+Learn how to +write +(and contribute please!) your own modules!
--You can read the full and up to date documentation on the py3status docs. -
+ + \ No newline at end of file