mirror of https://github.com/lcpz/lain.git
420 lines
14 KiB
Markdown
420 lines
14 KiB
Markdown
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](https://github.com/vain/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](http://www.gnu.org/licenses/gpl-2.0.html).
|
|
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](https://github.com/brunoos/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](http://docs.python.org/2/library/imaplib.html), 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](http://awesome.naquadah.org/doc/api/modules/naughty.html) 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](https://pypi.python.org/pypi/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](https://github.com/vain/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](https://bbs.archlinux.org/viewtopic.php?pid=1315135#p1315135).
|