From ec9d7e608aa0b5877b21a8af3f6011153d0d7c7c Mon Sep 17 00:00:00 2001 From: Ultrabug Date: Mon, 25 Mar 2019 10:06:25 +0100 Subject: [PATCH] update py3status documentation --- docs/user-contributed/py3status.html | 268 +++++++++++++++++---------- 1 file changed, 165 insertions(+), 103 deletions(-) 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.
+

Introducing py3status

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.

-

Usage

+

Documentation

-

-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

-

Handle i3bar click events from your 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 +

+ +

Using py3status modules

+ +

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"
 }
-

Use py3status modules on your i3bar

+

Clicking the modules

-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/
 }
-

Group modules to save space on your i3bar

+

Grouping the modules

-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 {
 }
-

Write your own modules to display your own stuff

+

Writing new modules for py3status

-

-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. -

+ -

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 -- 2.39.5