-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).
projects / etc / awesome.git / commitdiff