VAin agaIN

Author: Luke Bonham <dada [at] archlinux [dot] info>

Source: https://github.com/copycat-killer/vain

Version: 1.9.9

Release version: 2.0

Please note: until release version, this documentation will be not updated.

Foreword

Based on a port of awesome-vain, this costantly evolving module provides new layouts, a set of widgets and utility functions in order to improve Awesome usability and configurability.

This work is licensed under GNU GPLv2 License. Installation

Simply clone this repository into your Awesome directory.

Widgets

systemload

Show the current system load in a textbox. Read it directly from /proc/loadavg.

mysysload = vain.widgets.systemload()

A click on the widget will call htop in your terminal.

The function takes a table as an optional argument. That table may contain:

• .refresh_timeout: Default to 10 seconds.
• .show_all: Show all three values (true) or only the first one (false). Default to false.
• .color: Default to beautiful.bg_normal or "#FFFFFF".

cpu

Shows the average CPU usage percent for a given amount of time.

mycpuusage = vain.widgets.cpu()

A click on the widget will call htop in your terminal.

The function takes a table as optional argument, which can contain:

Variable	Meaning	Type	Default
refresh_timeout	Refresh timeout seconds	int	10
header	Text to show before value	string	" Vol "
header_color	Header color	string	beautiful.fg_normal or "#FFFFFF"
color	Value color	string	beautiful.fg_focus or "#FFFFFF"
footer	Text to show after value	string	"%"

Note: footer color is color.

memusage

Show used memory and total memory in MiB.

mymem = vain.widgets.mem()

The function takes a table as an optional argument. That table may contain:

Variable	Meaning	Type	Default
refresh_timeout	Refresh timeout seconds	int	10
show_swap	Show amount of used swap space?	boolean	false
show_total	Show amout of total memory?	boolean	false
header	Text to show before value	string	" Vol "
header_color	Header color	string	beautiful.fg_normal or "#FFFFFF"
color	Value color	string	beautiful.fg_focus or "#FFFFFF"
footer	Text to show after value	string	"MB"

Note: footer color is color.

mailcheck

Checks maildirs and shows the result in a textbox. Maildirs are structured as follows:

~/Mail
.
|-- arch
|   |-- cur
|   |-- new
|   `-- tmp
|-- gmail
|   |-- cur
|   |-- new
|   `-- tmp
.
.
.

therefore mailcheck checks whether there are files in the new directories. To do so, it calls find. If there's new mail, the textbox will say something like "mail: bugs(3), system(1)", otherwise it says "no mail".

mymailcheck = vain.widgets.mailcheck("/path/to/my/maildir")

The function takes a table as an optional argument. That table may contain:

• .mailprogram: Your favourite mail program. Clicking on the widget will spawn it. Default is mutt.
• .refresh_timeout: Default to 60 seconds.
• .mailpath: Path to your maildir, default is ~/Mail.
• .ignore_boxes: Another table which lists boxes (just the last part, like lists) to ignore. Default to an empty table.
• .initial_update: Check for mail when starting Awesome (true) or wait for the first refresh timeout (false)? Default to false.
• .header_text: Text to show along with output, default is "Mail".
• .header_text_color: Default to "#9E9E9E".
• .color_newmail: Default to "#D4D4D4".
• .color_nomail: Default to "#9E9E9E".
• .shadow: Hides widget when there are no mails. Default is false.

imapcheck

Check new mails over imap protocol.

Dependencies:

• Python3

Since luasec is still not officially supported in lua 5.2, writing a pure lua solution would have meant too many hacks and dependencies, resulting in a very big and not efficient-proven submodule.

That's why I chose Python.

Python offers imaplib, a simple yet powerful IMAP4 client library which provides encrypted communication over SSL sockets.

Basically, imapcheck calls vain/scripts/checkmail and parse its output in a widget. New mails are also notified through Naughty, with a popup like this:

+---------------------------------------------------+
| +---+                                             |
| |\ /| donald@disney.org has 3 new messages        |
| +---+                                             |
|       Latest From: Mickey Mouse <boss@disney.org> |
|       Subject: Re: Vacation Day                   |
|                                                   |
|       Not after what you did yesterday.           |
|       Daisy told me everything [...]              |
|                                                   |
+---------------------------------------------------+

Text will be cut if the mail is too long.

myimapcheck = vain.widgets.mailcheck(args)

The function takes a table as argument. Required table parameters are:

• .server: You email server. Example: imap.gmail.com.
• .mail: Your email.
• .password: Your email password.

while the optional are:

• .port: Imap port. Default is 993.
• .refresh_timeout: Default to 60 seconds.
• .notify_timeout: Notification timeout. Default to 8 seconds.
• .notify_position: Notification position. Default is "top_left". Check Naughty position parameter for a list of other possible values.
• .mailprogram: Your favourite mail program. Clicking on the widget will spawn it. Default is mutt.
• .mail_encoding: If you wish to set an encoding. Default is nil.
• .initial_update: Check for mail when starting Awesome (true) or wait for the first refresh timeout (false)? Default to false.
• .header_text: Text to show along with output, default is "Mail".
• .header_text_color: Default to "#9E9E9E".
• .color_newmail: Default to "#D4D4D4".
• .color_nomail: Default to "#9E9E9E".
• .shadow: Hides widget when there are no mails. Default is false.
• .maxlen: Maximum mail length. If mail is longer, it will be cut. Default is 100.
• .is_plain: Define whether .password field is a plain password (true) or a function that retrieves it (false). Default to false.

Let's focus better on .is_plain parameter.

You can just easily set your password like this:

args.is_plain = false
args.password = "mypassword"

and you'll have the same security provided by ~/.netrc. (In this case, it's better to set your rc.lua permissions to 700 or 600)

Or, you can use a keyring, like gnome's:

args.password = "gnome-keyring-query get password"

(gnome-keyring-query is not in gnome-keyring pkg, you have to download it separately)

or the very light python keyring.

When .is_plain is false, it executes .password before using it, so you can also use whatever password fetching solution you want.

You can also define your icon for the naughty notification. Just set vain_mail_notify into your theme.lua.

mpd

Provides a table with 2 elements:

• table["widget"] is a textbox displaying current song in play.

• table["force"] is a function to force the widget to update, exactly like vicious.force().

Also, a notification is shown when a new song is playing.

Dependencies:

• libnotify

• imagemagick

  mpdwidget = vain.widgets.mpd() ... right_layout:add(mpdwidget["widget"])

The function takes a table as an optional argument. That table may contain:

• .password: Mpd password. Default is unset.
• .host: Mpd host. Default is "127.0.0.1" (localhost).
• .port: Mpd port. Default is "6600".
• .music_dir: Your music directory. Default is "~/Music". If you have to change this, be sure to write the absolute path.
• .refresh_timeout: Widget refresh timeout. Default is 1.
• .notify_timeout: Notification timeout. Default is 5.
• .color_artist: Artist name color. Default is #9E9E9E.
• .color_song: Song name color. Default is #EBEBFF.
• .musicplr: Your favourite music player. Clicking on the widget will spawn it. Default is ncmpcpp.
• .shadow: Hides widget when no song is playing. Default is false.

You can use table["force"] to make your mpd keybindings immediate. Example usage:

globalkeys = awful.util.table.join(
...
    -- Music control
    awful.key({ altkey, "Control" }, "Up", function ()
                                              awful.util.spawn_with_shell( "mpc toggle || ncmpcpp toggle || ncmpc toggle || pms toggle", false )
                                              mpdwidget["force"]()
                                           end),
    awful.key({ altkey, "Control" }, "Down", function ()
                                              awful.util.spawn_with_shell( "mpc stop || ncmpcpp stop || ncmpc stop || pms stop", false )
                                              mpdwidget["force"]()
                                             end ),
    awful.key({ altkey, "Control" }, "Left", function ()
                                              awful.util.spawn_with_shell( "mpc prev || ncmpcpp prev || ncmpc prev || pms prev", false )
                                              mpdwidget["force"]()
                                             end ),
    awful.key({ altkey, "Control" }, "Right", function ()
                                              awful.util.spawn_with_shell( "mpc next || ncmpcpp next || ncmpc next || pms next", false )
                                              mpdwidget["force"]()
                                              end ),

net

Monitors network interfaces and shows current traffic in a textbox. If the interface is not present or if there's not enough data yet, you'll see wlan0: - or similar. Otherwise, the current traffic is shown in kilobytes per second as eth0: ↑(00,010.2), ↓(01,037.8) or similar.

neteth0 = vain.widgets.net()

The function takes a table as an optional argument. That table may contain:

• .iface: Default to eth0.
• .refresh_timeout: Default to 2 seconds.
• .color: Default to beautiful.bg_normal or "#FFFFFF".

gitodo

This is an integration of gitodo into Awesome.

todolist = vain.widgets.gitodo()

The function takes a table as an optional argument. That table may contain:

• .refresh_timeout: Default to 120 seconds.
• .initial_update: Check for todo items when starting Awesome (true) or wait for the first refresh timeout (false)? Default to true.

beautiful.gitodo_normal is used as the color for non-outdated items, beautiful.gitodo_warning for those items close to their deadline and beautiful.gitodo_outdated is the color of outdated items.

Utility functions

I'll only explain the more complex functions. See the source code for the others.

menu_clients_current_tags

Similar to awful.menu.clients(), but this menu only shows the clients of currently visible tags. Use it like this:

globalkeys = awful.util.table.join(
    ...
    awful.key({ "Mod1" }, "Tab", function()
        awful.menu.menu_keys.down = { "Down", "Alt_L", "Tab", "j" }
        awful.menu.menu_keys.up = { "Up", "k" }
        vain.util.menu_clients_current_tags({ width = 350 }, { keygrabber = true })
    end),
    ...
)

magnify_client

Set a client to floating and resize it in the same way the "magnifier" layout does it. Place it on the "current" screen (derived from the mouse position). This allows you to magnify any client you wish, regardless of the currently used layout. Use it with a client keybinding like this:

clientkeys = awful.util.table.join(
	...
	awful.key({ modkey, "Control" }, "m", vain.util.magnify_client),
	...
)

If you want to "de-magnify" it, just reset the clients floating state to false (hit Mod4+CTRL+Space, for example).

niceborder_{focus, unfocus}

By default, your rc.lua contains something like this:

client.connect_signal("focus", function(c) c.border_color = beautiful.border_focus end)
client.connect_signal("unfocus", function(c) c.border_color = beautiful.border_normal end)

You can change it to this:

client.connect_signal("focus", vain.util.niceborder_focus(c))
client.connect_signal("unfocus", vain.util.niceborder_unfocus(c))

Now, when a client is focused or unfocused, Awesome will look up its nice value in /proc/<pid>/stat. If it's less than 0, the client is classified as "high priority"; if it's greater than 0, the client is classified as "low priority". If it's equal to 0, nothing special happens.

This requires to define additional colors in your theme.lua. For example:

theme.border_focus_highprio  = "#FF0000"
theme.border_normal_highprio = "#A03333"

theme.border_focus_lowprio   = "#3333FF"
theme.border_normal_lowprio  = "#333366"

tag_view_nonempty

This function lets you jump to the next/previous non-empty tag. It takes two arguments:

• direction: 1 for next non-empty tag, -1 for previous.
• sc: Screen in which the taglist is. Default is mouse.screen or 1. This argument is optional.

Usage example:

globalkeys = awful.util.table.join(
	...
    -- Non-empty tag browsing
    awful.key({ altkey }, "Left", function () vain.util.tag_view_nonempty(-1)
end),
    awful.key({ altkey }, "Right", function () vain.util.tag_view_nonempty(1) end),
    ...

prompt_rename_tag

This function enables you to dynamically rename the current tag you have focused. Usage example:

globalkeys = awful.util.table.join(
    ..
    -- Dynamic tag renaming
	awful.key({ modkey, "Shift" }, "r", function () vain.util.prompt_rename_tag(mypromptbox) end),
	...

Credits goes to minism.