cheri/dotfiles
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Initial commit

Browse source
This commit is contained in:
vibikim 2020-05-16 23:07:21 +03:00
commit c5703aca02
373 changed files with 12401 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

43
awesome/lain/wiki/Home.md Normal file
View file

@ -0,0 +1,43 @@
Welcome to the Lain wiki!
If you spot a typo or have a suggestion to improve these pages, please notify me opening an [issue](https://github.com/lcpz/lain/issues) format. Thank you.
Dependencies
------------
Package | Requested by | Reasons of choice
--- | --- | ---
[curl](https://curl.haxx.se) | `imap`, `mpd`, and `weather` widgets | 1. faster and simpler to use than [LuaSocket](https://github.com/diegonehab/luasocket); 2. it's in the core of almost every distro; 3. can be called [asynchronously](https://awesomewm.org/doc/api/libraries/awful.spawn.html#easy_async)
GLib >= 2.54 | `fs` widget | Pure Awesome/Lua implementation.
The second dependency will be removed once all major distros update their Gio/Glib versions.
Installation
------------
### Arch Linux
[AUR package](https://aur.archlinux.org/packages/lain-git/)
### Other distributions
```shell
git clone https://github.com/lcpz/lain.git ~/.config/awesome/lain
```
Also available via [LuaRocks](https://luarocks.org/modules/aajjbb/lain).
Usage
--------
First, include it into your `rc.lua`:
```lua
local lain = require("lain")
```
Then check out the submodules you want:
- [Layouts](https://github.com/lcpz/lain/wiki/Layouts)
- [Widgets](https://github.com/lcpz/lain/wiki/Widgets)
- [Utilities](https://github.com/lcpz/lain/wiki/Utilities)

255
awesome/lain/wiki/Layouts.md Normal file
View file

@ -0,0 +1,255 @@
lain/layout
.
|-- termfair
|-- termfair.center
|-- cascade
|-- cascade.tile
|-- centerwork
|-- centerwork.horizontal
Usage
=====
As usual, specify your favourites in `awful.layout.layouts`, or set them on specific tags with [`awful.layout.set`](https://awesomewm.org/doc/api/libraries/awful.layout.html#set).
```lua
awful.layout.set(lain.layout.termfair, tag)
```
How do layouts work?
====================
`termfair`
--------
This layout restricts the size of each window. Each window will have the
same width but is variable in height. Furthermore, windows are
left-aligned. The basic workflow is as follows (the number above the
screen is the number of open windows, the number in a cell is the fixed
number of a client):
(1) (2) (3)
+---+---+---+ +---+---+---+ +---+---+---+
| | | | | | | | | | | |
| 1 | | | -> | 2 | 1 | | -> | 3 | 2 | 1 | ->
| | | | | | | | | | | |
+---+---+---+ +---+---+---+ +---+---+---+
(4) (5) (6)
+---+---+---+ +---+---+---+ +---+---+---+
| 4 | | | | 5 | 4 | | | 6 | 5 | 4 |
+---+---+---+ -> +---+---+---+ -> +---+---+---+
| 3 | 2 | 1 | | 3 | 2 | 1 | | 3 | 2 | 1 |
+---+---+---+ +---+---+---+ +---+---+---+
The first client will be located in the left column. When opening
another window, this new window will be placed in the left column while
moving the first window into the middle column. Once a row is full,
another row above it will be created.
Default number of columns and rows are respectively taken from `nmaster`
and `ncol` values in `awful.tag`, but you can set your own.
For example, this sets `termfair` to 3 columns and at least 1 row:
```lua
lain.layout.termfair.nmaster = 3
lain.layout.termfair.ncol = 1
```
`termfair.center`
----------
Similar to `termfair`, but with fixed number of vertical columns. Cols are centerded until there are `nmaster` columns, then windows are stacked as slaves, with possibly `ncol` clients per column at most.
(1) (2) (3)
+---+---+---+ +-+---+---+-+ +---+---+---+
| | | | | | | | | | | | |
| | 1 | | -> | | 1 | 2 | | -> | 1 | 2 | 3 | ->
| | | | | | | | | | | | |
+---+---+---+ +-+---+---+-+ +---+---+---+
(4) (5)
+---+---+---+ +---+---+---+
| | | 3 | | | 2 | 4 |
+ 1 + 2 +---+ -> + 1 +---+---+
| | | 4 | | | 3 | 5 |
+---+---+---+ +---+---+---+
Like `termfair`, default number of columns and rows are respectively taken from `nmaster`
and `ncol` values in `awful.tag`, but you can set your own.
For example, this sets `termfair.center` to 3 columns and at least 1 row:
```lua
lain.layout.termfair.center.nmaster = 3
lain.layout.termfair.center.ncol = 1
```
`cascade`
-------
Cascade all windows of a tag.
You can control the offsets by setting these two variables:
```lua
lain.layout.cascade.offset_x = 64
lain.layout.cascade.offset_y = 16
```
The following reserves space for 5 windows:
```lua
lain.layout.cascade.nmaster = 5
```
That is, no window will get resized upon the creation of a new window,
unless there's more than 5 windows.
`cascade.tile`
-----------
Similar to `awful.layout.suit.tile` layout, however, clients in the slave
column are cascaded instead of tiled.
Left column size can be set, otherwise is controlled by `mwfact` of the
tag. Additional windows will be opened in another column on the right.
New windows are placed above old windows.
Whether the slave column is placed on top of the master window or not is
controlled by the value of `ncol`. A value of 1 means "overlapping slave column"
and anything else means "don't overlap windows".
Usage example:
```lua
lain.layout.cascade.tile.offset_x = 2
lain.layout.cascade.tile.offset_y = 32
lain.layout.cascade.tile.extra_padding = 5
lain.layout.cascade.tile.nmaster = 5
lain.layout.cascade.tile.ncol = 2
```
`extra_padding` reduces the size of the master window if "overlapping
slave column" is activated. This allows you to see if there are any
windows in your slave column.
Setting `offset_x` to a very small value or even 0 is recommended to avoid wasting space.
`centerwork`
----------
You start with one window, centered horizontally:
+--------------------------+
| +----------+ |
| | | |
| | | |
| | | |
| | MAIN | |
| | | |
| | | |
| | | |
| | | |
| +----------+ |
+--------------------------+
This is your main working window. You do most of the work right here.
Sometimes, you may want to open up additional windows. They're put on left and right, alternately.
+--------------------------+
| +---+ +----------+ +---+ |
| | | | | | | |
| | | | | | | |
| | | | | | | |
| +---+ | MAIN | +---+ |
| +---+ | | +---+ |
| | | | | | | |
| | | | | | | |
| | | | | | | |
| +---+ +----------+ +---+ |
+--------------------------+
*Please note:* If you use Awesome's default configuration, navigation in
this layout may be very confusing. How do you get from the main window
to satellite ones depends on the order in which the windows are opened.
Thus, use of `awful.client.focus.bydirection()` is suggested.
Here's an example:
```lua
globalkeys = awful.util.table.join(
-- [...]
awful.key({ modkey }, "j",
function()
awful.client.focus.bydirection("down")
if client.focus then client.focus:raise() end
end),
awful.key({ modkey }, "k",
function()
awful.client.focus.bydirection("up")
if client.focus then client.focus:raise() end
end),
awful.key({ modkey }, "h",
function()
awful.client.focus.bydirection("left")
if client.focus then client.focus:raise() end
end),
awful.key({ modkey }, "l",
function()
awful.client.focus.bydirection("right")
if client.focus then client.focus:raise() end
end),
-- [...]
)
```
`centerwork.horizontal`
-----------
Same as `centerwork`, except that the main
window expands horizontally, and the additional windows
are put ontop/below it. Useful if you have a screen turned 90°.
Pre 4.0 `uselesstile` patches
=============================
In branch 3.5, this module provided useless gaps layouts. Since useless gaps have been implemented in Awesome 4.0, those layouts have been removed.
Following are a couple of `uselesstile` variants that were not part of lain. They are kept only for reference and are not supported.
Xmonad-like
-----------
If you want to have `awful.layout.suit.tile` behave like xmonad, with internal gaps two times wider than external ones, download [this](https://gist.github.com/lcpz/9e56dcfbe66bfe14967c) as `lain/layout/uselesstile`.
Inverted master
---------------
Want to invert master window position? Use [this](https://gist.github.com/lcpz/c59dc59c9f99d98218eb) version. You can set `single_gap` with `width` and `height` in your `theme.lua`, in order to define the window geometry when there's only one client, otherwise it goes maximized. An example:
theme.single_gap = { width = 600, height = 100 }
What about layout icons?
========================
They are located in ``lain/icons/layout``.
To use them, define new `layout_*` variables in your ``theme.lua``. For instance:
```lua
theme.lain_icons = os.getenv("HOME") ..
"/.config/awesome/lain/icons/layout/default/"
theme.layout_termfair = theme.lain_icons .. "termfair.png"
theme.layout_centerfair = theme.lain_icons .. "centerfair.png" -- termfair.center
theme.layout_cascade = theme.lain_icons .. "cascade.png"
theme.layout_cascadetile = theme.lain_icons .. "cascadetile.png" -- cascade.tile
theme.layout_centerwork = theme.lain_icons .. "centerwork.png"
theme.layout_centerworkh = theme.lain_icons .. "centerworkh.png" -- centerwork.horizontal
```
Credit goes to [Nicolas Estibals](https://github.com/nestibal) for creating
layout icons for default theme.
You can use them as a template for your custom versions.

338
awesome/lain/wiki/Utilities.md Normal file
View file

@ -0,0 +1,338 @@
Quake
-----
A Quake-like dropdown container for your favourite application.
**Usage**
Define it globally to have a single instance for all screens:
```lua
local quake = lain.util.quake()
```
or define it in `connect_for_each_screen` to have one instance for each screen:
```lua
awful.screen.connect_for_each_screen(function(s)
-- Quake application
s.quake = lain.util.quake()
-- [...]
```
**Keybinding example**
If using a global instance:
```lua
awful.key({ modkey, }, "z", function () quake:toggle() end),
```
If using a per-screen instance:
```lua
awful.key({ modkey, }, "z", function () awful.screen.focused().quake:toggle() end),
```
**Input table**
Variable | Meaning | Type | Default
--- | --- | --- | ---
`app` | client to spawn | string | "xterm"
`name` | client name | string | "QuakeDD"
`argname` | how to specify client name | string | "-name %s"
`extra` | extra `app` arguments | string | empty string
`border` | border width | integer | 1
`visible` | initially visible | boolean | false
`followtag` | always spawn on currently focused screen | boolean | false
`overlap` | Overlap the wibox or not | boolean | false
`settings` | Additional settings to make on the client | function | `nil`
`screen` | screen where to spawn the client | integer | `awful.screen.focused()`
`height` | dropdown client height | float in [0,1] or exact pixels number | 0.25
`width` | dropdown client width | float in [0,1] or exact pixels number | 1
`vert` | vertical position | string, possible values: "top", "bottom", "center" | "top"
`horiz` | horizontal position | string, possible values: "left", "right", "center" | "left"
`height` and `width` express a fraction of the workspace.
`settings` is a function which takes the client as input, and can be used to customize its properties. For instance:
```lua
-- set the client sticky
s.quake = lain.util.quake { settings = function(c) c.sticky = true end }
```
Read [here](https://awesomewm.org/doc/api/classes/client.html#Object_properties) for the complete list of properties.
**Notes**
* [Does not work](https://github.com/lcpz/lain/issues/358) with `gnome-terminal`, `konsole`, or any other terminal which is strictly designed for a Desktop Environment. Just pick a better terminal, [there's plenty](https://wiki.archlinux.org/index.php/List_of_applications#Terminal_emulators).
* Set `followtag = true` if [experiencing issues with multiple screens](https://github.com/lcpz/lain/issues/346).
* If you have a `awful.client.setslave` rule for your application, ensure you use an exception for `QuakeDD` (or your defined `name`). Otherwise, you may run into problems with focus.
* If you are using a VTE-based terminal like `termite`, be sure to set [`argname = "--name %s"`](https://github.com/lcpz/lain/issues/211).
Separators
----------
Adds Cairo separators.
```lua
local separators = lain.util.separators
```
A separator function `separators.separator` takes two color arguments, defined as strings. `"alpha"` argument is allowed. Example:
```lua
arrl_dl = separators.arrow_left(beautiful.bg_focus, "alpha")
arrl_ld = separators.arrow_left("alpha", beautiful.bg_focus)
```
You can customize height and width by setting `separators_height` and `separators_width` in your `theme.lua`. Default values are 0 and 9, respectively.
List of functions:
+-- separators
|
|`-- arrow_right() Draw a right arrow.
`-- arrow_left() Draw a left arrow.
markup
------
Mades markup easier.
```lua
local markup = lain.util.markup
```
List of functions:
+-- markup
|
|`-- bold() Set bold.
|`-- italic() Set italicized text.
|`-- strike() Set strikethrough text.
|`-- underline() Set underlined text.
|`-- monospace() Set monospaced text.
|`-- big() Set bigger text.
|`-- small() Set smaller text.
|`-- font() Set the font of the text.
|`-- font() Set the font of the text.
|`-- color() Set background and foreground color.
|`-- fontfg() Set font and foreground color.
|`-- fontbg() Set font and background color.
`-- fontcolor() Set font, plus background and foreground colors.
|
|`--+ bg
| |
| `-- color() Set background color.
|
`--+ fg
|
`-- color() Set foreground color.
they all take one argument, which is the text to markup, except the following:
```lua
markup.font(font, text)
markup.color(fg, bg, text)
markup.fontfg(font, fg, text)
markup.fontbg(font, bg, text)
markup.fontcolor(font, fg, bg, text)
markup.fg.color(color, text)
markup.bg.color(color, text)
```
Dynamic tagging
---------------
That is:
- add a new tag;
- rename current tag;
- move current tag;
- delete current tag.
If you delete a tag, any rule set on it shall be broken, so be careful.
Use it with key bindings like these:
```lua
awful.key({ modkey, "Shift" }, "n", function () lain.util.add_tag(mylayout) end),
awful.key({ modkey, "Shift" }, "r", function () lain.util.rename_tag() end),
awful.key({ modkey, "Shift" }, "Left", function () lain.util.move_tag(1) end), -- move to next tag
awful.key({ modkey, "Shift" }, "Right", function () lain.util.move_tag(-1) end), -- move to previous tag
awful.key({ modkey, "Shift" }, "d", function () lain.util.delete_tag() end),
```
The argument in `lain.util.add_tag` represents the tag layout, and is optional: if not present, it will be defaulted to `awful.layout.suit.tile`.
Useless gaps resize
---------------------
Changes `beautiful.useless_gaps` on the fly.
```lua
lain.util.useless_gap_resize(thatmuch, s, t)
```
The argument `thatmuch` is the number of pixel to add to/substract from gaps (integer).
The arguments `s` and `t` are the `awful.screen` and `awful.tag` in which you want to change the gap. They are optional.
Following are example keybindings for changing client gaps on current screen and tag.
Example 1:
```lua
-- On the fly useless gaps change
awful.key({ altkey, "Control" }, "+", function () lain.util.useless_gaps_resize(1) end),
awful.key({ altkey, "Control" }, "-", function () lain.util.useless_gaps_resize(-1) end),
```
where `altkey = Mod1`. Example 2:
```lua
mywidget:buttons(awful.util.table.join (
awful.button({}, 4, function() lain.util.useless_gaps_resize(-1) end),
awful.button({}, 5, function() lain.util.useless_gaps_resize(1) end)
end)
))
```
so when hovering the mouse over `mywidget`, you can adjust useless gaps size by scrolling with the mouse wheel.
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 which the taglist is in. Default is `mouse.screen` or `1`. This
argument is optional.
You can use it with key bindings like these:
```lua
-- Non-empty tag browsing
awful.key({ altkey }, "Left", function () lain.util.tag_view_nonempty(-1) end),
awful.key({ altkey }, "Right", function () lain.util.tag_view_nonempty(1) end),
```
where `altkey = "Mod1"`.
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:
```lua
clientkeys = awful.util.table.join(
-- [...]
awful.key({ modkey, "Control" }, "m", lain.util.magnify_client),
-- [...]
)
```
If you want to "de-magnify" it, just retype the keybinding.
If you want magnified client to respond to `incmwfact`, read [here](https://github.com/lcpz/lain/issues/195).
menu\_clients\_current\_tags
----------------------------
Similar to `awful.menu.clients`, but this menu only shows the clients
of currently visible tags. Use it with a key binding like this:
```lua
awful.key({ "Mod1" }, "Tab", function()
lain.util.menu_clients_current_tags({ width = 350 }, { keygrabber = true })
end),
```
menu\_iterator
--------------
A generic menu utility which enables iteration over lists of possible
actions to execute. The perfect example is a menu for choosing what
configuration to apply to X with `xrandr`, as suggested on the [Awesome wiki page](https://awesomewm.org/recipes/xrandr).
<p align="center">
<img src="https://user-images.githubusercontent.com/4147254/36317474-3027f8b6-130b-11e8-9b6b-9a2cf55ae841.gif"/>
<br>An example Synergy menu, courtesy of <a href="https://github.com/sim590/dotfiles/blob/master/awesome/rc/xrandr.lua">sim590</a>
</p>
You can either manually create a menu by defining a table in this format:
```lua
{ { "choice description 1", callbackFuction1 }, { "choice description 2", callbackFunction2 }, ... }
```
or use `lain.util.menu_iterator.menu`. Once you have your menu, use it with `lain.menu_iterator.iterate`.
### Input tables
**lain.menu_iterator.iterate**
| Argument | Description | Type
|---|---| ---
| `menu` | the menu to iterate on | table
| `timeout` | time (in seconds) to wait on a choice before the choice is accepted | integer (default: 4)
| `icon` | path to the icon to display in `naughty.notify` window | string
**lain.menu_iterator.menu**
| Argument | Description | Type
|---|---| ---
`choices` | list of choices (e.g., `{ "choice1", "choice2", ... }`) | array of strings
`name` | name of the program related to this menu | string
`selected_cb` | callback to execute for each selected choice, it takes one choice (string) as argument; can be `nil` (no action to execute) | function
`rejected_cb` | callback to execute for all rejected choices (the remaining choices, once one is selected), it takes one choice (string) as argument; can be `nil` (no action to execute) | function
`extra_choices` | more choices to be added to the menu; unlike `choices`, these ones won't trigger `rejected_cb` | array of `{ choice, callback }` pairs, where `choice` is a string and `callback` is a function
`combination` | how choices have to be combined in the menu; possible values are: "single" (default), the set of possible choices will simply be the input set ; "powerset", the set of possible choices will be the [power set](https://en.wikipedia.org/wiki/Power_set) of the input set | string
### Examples
A simple example is:
```lua
local mymenu_iterable = lain.util.menu_iterator.menu {
choices = {"My first choice", "My second choice"},
name = "My awesome program",
selected_cb = function(choice)
-- do something with selected choice
end,
rejected_cb = function(choice)
-- do something with every rejected choice
end
}
```
The variable `mymenu_iterable` is a menu compatible with the function `lain.util.menu_iterator.iterate`, which will iterate over it and displays notification with `naughty.notify` every time it is called. You can use it like this:
```lua
local confirm_timeout = 5 -- time to wait before confirming the menu selection
local my_notify_icon = "/path/to/icon" -- the icon to display in the notification
lain.util.menu_iterator.iterate(mymenu_iterable, confirm_timeout, my_notify_icon)
```
Once `confirm_timeout` has passed without anymore calls to `iterate`, the choice is made and the associated callbacks (both for selected and rejected choices) are spawned.
A useful practice is to add a `Cancel` option as an extra choice for canceling a menu selection. Extending the above example:
```lua
local mymenu_iterable = lain.util.menu_iterator.menu {
choices = {"My first choice", "My second choice"},
name = "My awesome program",
selected_cb = function(choice)
-- do something with selected choice
end,
rejected_cb = function(choice)
-- do something with every rejected choice
end
-- nil means no action to do
extra_choices = { {"Cancel"}, nil }
}
```

55
awesome/lain/wiki/Widgets.md Normal file
View file

@ -0,0 +1,55 @@
# Usage
Every lain widget is a table.
A lain widget is generated by a `function`.
The `function` signature, input and output arguments can be found in the [related wiki entry](https://github.com/lcpz/lain/wiki/Widgets#index).
Every lain widget contains a `wibox.widget`, which is updated by a timed function. To access the widget, use the field `widget`, while to access the timed function, use the field `update`. Some lain widgets may also have an `icon` field, which is a `wibox.widget.imagebox`, and/or a `timer` field, which is the `gears.timer` on `update`.
Every `function` may take either a table or a list of variables as input.
If the input is a table, you must define a function variable called `settings` in it. There you will be able to define `widget` appearance.
For instance, if `widget` is a textbox, to markup it call `widget:set_markup(...)` within `settings`.
In the scope of `settings` you can use predefined arguments, which are specified in the wiki entries.
Example of a lain widget:
```lua
local cpu = lain.widget.cpu {
settings = function()
widget:set_markup("Cpu " .. cpu_now.usage)
end
}
-- to access the widget: cpu.widget
```
If you want to see some applications, check [awesome-copycats](https://github.com/lcpz/awesome-copycats).
# Index
- [alsa](https://github.com/lcpz/lain/wiki/alsa)
- [alsabar](https://github.com/lcpz/lain/wiki/alsabar)
- [bat](https://github.com/lcpz/lain/wiki/bat)
- [cal](https://github.com/lcpz/lain/wiki/cal)
- [cpu](https://github.com/lcpz/lain/wiki/cpu)
- [fs](https://github.com/lcpz/lain/wiki/fs)
- [imap](https://github.com/lcpz/lain/wiki/imap)
- [mem](https://github.com/lcpz/lain/wiki/mem)
- [mpd](https://github.com/lcpz/lain/wiki/mpd)
- [net](https://github.com/lcpz/lain/wiki/net)
- [pulse](https://github.com/lcpz/lain/wiki/pulse)
- [pulsebar](https://github.com/lcpz/lain/wiki/pulsebar)
- [sysload](https://github.com/lcpz/lain/wiki/sysload)
- [temp](https://github.com/lcpz/lain/wiki/temp)
- [weather](https://github.com/lcpz/lain/wiki/weather)
## Users contributed
- [moc](https://github.com/lcpz/lain/wiki/moc)
- [redshift](https://github.com/lcpz/lain/wiki/redshift)
- [task](https://github.com/lcpz/lain/wiki/task)
- [tp_smapi](https://github.com/lcpz/lain/wiki/tp_smapi)

1
awesome/lain/wiki/_Footer.md Normal file
View file

@ -0,0 +1 @@
[Home](https://github.com/lcpz/lain/wiki) • [Layouts](https://github.com/lcpz/lain/wiki/Layouts) • [Widgets](https://github.com/lcpz/lain/wiki/Widgets) • [Utilities](https://github.com/lcpz/lain/wiki/Utilities)

26
awesome/lain/wiki/_Sidebar.md Normal file
View file

@ -0,0 +1,26 @@
* [Home](https://github.com/lcpz/lain/wiki/Home)
* [Layouts](https://github.com/lcpz/lain/wiki/Layouts)
* [Usage](https://github.com/lcpz/lain/wiki/Layouts#Usage)
* [How do layouts work?](https://github.com/lcpz/lain/wiki/Layouts#how-do-layouts-work)
* [termfair](https://github.com/lcpz/lain/wiki/Layouts#termfair)
* [centerfair](https://github.com/lcpz/lain/wiki/Layouts#termfaircenter)
* [cascade](https://github.com/lcpz/lain/wiki/Layouts#cascade)
* [cascadetile](https://github.com/lcpz/lain/wiki/Layouts#cascadetile)
* [centerwork](https://github.com/lcpz/lain/wiki/Layouts#centerwork)
* [centerworkh](https://github.com/lcpz/lain/wiki/Layouts#centerworkhorizontal)
* [Pre 4.0 uselesstile patches](https://github.com/lcpz/lain/wiki/Layouts#pre-40-uselesstile-patches)
* [What about layout icons?](https://github.com/lcpz/lain/wiki/Layouts#what-about-layout-icons)
* [Widgets](https://github.com/lcpz/lain/wiki/Widgets)
* [Usage](https://github.com/lcpz/lain/wiki/Widgets#usage)
* [Index](https://github.com/lcpz/lain/wiki/Widgets#index)
* [Users contributed](https://github.com/lcpz/lain/wiki/Widgets#users-contributed)
* [Utilities](https://github.com/lcpz/lain/wiki/Utilities)
* [quake](https://github.com/lcpz/lain/wiki/Utilities#quake)
* [separators](https://github.com/lcpz/lain/wiki/Utilities#separators)
* [markup](https://github.com/lcpz/lain/wiki/Utilities#markup)
* [dynamic tagging](https://github.com/lcpz/lain/wiki/Utilities#dynamic-tagging)
* [useless_gaps_resize](https://github.com/lcpz/lain/wiki/Utilities#useless-gaps-resize)
* [tag_view_non_empty](https://github.com/lcpz/lain/wiki/Utilities#tag_view_nonempty)
* [magnify_client](https://github.com/lcpz/lain/wiki/Utilities#magnify_client)
* [menu_clients_current_tags](https://github.com/lcpz/lain/wiki/Utilities#menu_clients_current_tags)
* [menu_iterator](https://github.com/lcpz/lain/wiki/Utilities#menu_iterator)

148
awesome/lain/wiki/alsa.md Normal file
View file

@ -0,0 +1,148 @@
## Usage
[Read here.](https://github.com/lcpz/lain/wiki/Widgets#usage)
### Description
Shows ALSA volume.
```lua
local volume = lain.widget.alsa()
```
## Input table
Variable | Meaning | Type | Default
--- | --- | --- | ---
`timeout` | Refresh timeout (in seconds) | integer | 5
`cmd` | Alsa mixer command | string | "amixer"
`channel` | Mixer channel | string | "Master"
`togglechannel` | Toggle channel | string | `nil`
`settings` | User settings | function | empty function
`cmd` is useful if you need to pass additional arguments to amixer. For instance, you may want to define `cmd = "amixer -c X"` in order to set amixer with card `X`.
`settings` can use the following variables:
Variable | Meaning | Type | Values
--- | --- | --- | ---
`volume_now.level` | Volume level | integer | 0-100
`volume_now.status` | Device status | string | "on", "off"
## Output table
Variable | Meaning | Type
--- | --- | ---
`widget` | The widget | `wibox.widget.textbox`
`channel` | ALSA channel | string
`update` | Update `widget` | function
## Toggle channel
In case mute toggling can't be mapped to master channel (this happens, for instance, when you are using an HDMI output), define togglechannel as your S/PDIF device. You can get the device ID with `scontents` command.
For instance, if card number is 1 and S/PDIF number is 3:
```shell
$ amixer -c 1 scontents
Simple mixer control 'Master',0
Capabilities: volume
Playback channels: Front Left - Front Right
Capture channels: Front Left - Front Right
Limits: 0 - 255
Front Left: 255 [100%]
Front Right: 255 [100%]
Simple mixer control 'IEC958',0
Capabilities: pswitch pswitch-joined
Playback channels: Mono
Mono: Playback [on]
Simple mixer control 'IEC958',1
Capabilities: pswitch pswitch-joined
Playback channels: Mono
Mono: Playback [on]
Simple mixer control 'IEC958',2
Capabilities: pswitch pswitch-joined
Playback channels: Mono
Mono: Playback [on]
Simple mixer control 'IEC958',3
Capabilities: pswitch pswitch-joined
Playback channels: Mono
Mono: Playback [on]
```
you have to set `togglechannel = "IEC958,3"`.
## Buttons
If you want buttons, just add the following after your widget in `rc.lua`.
```lua
volume.widget:buttons(awful.util.table.join(
awful.button({}, 1, function() -- left click
awful.spawn(string.format("%s -e alsamixer", terminal))
end),
awful.button({}, 2, function() -- middle click
os.execute(string.format("%s set %s 100%%", volume.cmd, volume.channel))
volume.update()
end),
awful.button({}, 3, function() -- right click
os.execute(string.format("%s set %s toggle", volume.cmd, volume.togglechannel or volume.channel))
volume.update()
end),
awful.button({}, 4, function() -- scroll up
os.execute(string.format("%s set %s 1%%+", volume.cmd, volume.channel))
volume.update()
end),
awful.button({}, 5, function() -- scroll down
os.execute(string.format("%s set %s 1%%-", volume.cmd, volume.channel))
volume.update()
end)
))
```
## Keybindings
You can control the widget with keybindings like these:
```lua
-- ALSA volume control
awful.key({ altkey }, "Up",
function ()
os.execute(string.format("amixer set %s 1%%+", volume.channel))
volume.update()
end),
awful.key({ altkey }, "Down",
function ()
os.execute(string.format("amixer set %s 1%%-", volume.channel))
volume.update()
end),
awful.key({ altkey }, "m",
function ()
os.execute(string.format("amixer set %s toggle", volume.togglechannel or volume.channel))
volume.update()
end),
awful.key({ altkey, "Control" }, "m",
function ()
os.execute(string.format("amixer set %s 100%%", volume.channel))
volume.update()
end),
awful.key({ altkey, "Control" }, "0",
function ()
os.execute(string.format("amixer set %s 0%%", volume.channel))
volume.update()
end),
```
where `altkey = "Mod1"`.
### Muting with PulseAudio
If you are using this widget in conjuction with PulseAudio, add the option `-D pulse` to the muting keybinding, like this:
```lua
awful.key({ altkey }, "m",
function ()
os.execute(string.format("amixer -D pulse set %s toggle", volume.togglechannel or volume.channel))
volume.update()
end),
```

102
awesome/lain/wiki/alsabar.md Normal file
View file

@ -0,0 +1,102 @@
## Usage
[Read here.](https://github.com/lcpz/lain/wiki/Widgets#usage)
### Description
Shows ALSA volume with a progressbar; provides tooltips and notifications.
```lua
local volume = lain.widget.alsabar()
```
## Input table
Variable | Meaning | Type | Default
--- | --- | --- | ---
`timeout` | Refresh timeout (in seconds) | integer | 5
`settings` | User settings | function | empty function
`width` | Bar width | number | 63
`height` | Bar height | number | 1
`margins` | Bar margins | number | 1
`paddings` | Bar paddings | number | 1
`ticks` | Set bar ticks on | boolean | false
`ticks_size` | Ticks size | integer | 7
`cmd` | ALSA mixer command | string | "amixer"
`channel` | Mixer channel | string | "Master"
`togglechannel` | Toggle channel | string | `nil`
`colors` | Bar colors | table | see [Default colors](https://github.com/lcpz/lain/wiki/alsabar#default-colors)
`notification_preset` | Notification preset | table | See [default `notification_preset`](https://github.com/lcpz/lain/wiki/alsabar#default-notification_preset)
`followtag` | Display the notification on currently focused screen | boolean | false
`cmd` is useful if you need to pass additional arguments to `amixer`. For instance, you may want to define `cmd = "amixer -c X"` in order to set amixer with card `X`.
In case mute toggling can't be mapped to master channel (this happens, for instance, when you are using an HDMI output), define `togglechannel` as your S/PDIF device. Read [`alsa`](https://github.com/lcpz/lain/wiki/alsa#toggle-channel) page to know how.
`settings` can use the following variables:
Variable | Meaning | Type | Values
--- | --- | --- | ---
`volume_now.level` | Volume level | integer | 0-100
`volume_now.status` | Device status | string | "on", "off"
With multiple screens, the default behaviour is to show a visual notification pop-up window on the first screen. By setting `followtag` to `true` it will be shown on the currently focused tag screen.
### Default colors
Variable | Meaning | Type | Default
--- | --- | --- | ---
`background` | Bar backgrund color | string | "#000000"
`mute` | Bar mute color | string | "#EB8F8F"
`unmute` | Bar unmute color | string | "#A4CE8A"
### Default `notification_preset`
```lua
notification_preset = {
font = "Monospace 10"
}
```
## Output table
Variable | Meaning | Type
--- | --- | ---
`bar` | The widget | `wibox.widget.progressbar`
`channel` | ALSA channel | string
`notify` | The notification | function
`update` | Update `bar` | function
`tooltip` | The tooltip | `awful.tooltip`
## Buttons
If you want buttons, just add the following after your widget in `rc.lua`.
```lua
volume.bar:buttons(awful.util.table.join(
awful.button({}, 1, function() -- left click
awful.spawn(string.format("%s -e alsamixer", terminal))
end),
awful.button({}, 2, function() -- middle click
os.execute(string.format("%s set %s 100%%", volume.cmd, volume.channel))
volume.update()
end),
awful.button({}, 3, function() -- right click
os.execute(string.format("%s set %s toggle", volume.cmd, volume.togglechannel or volume.channel))
volume.update()
end),
awful.button({}, 4, function() -- scroll up
os.execute(string.format("%s set %s 1%%+", volume.cmd, volume.channel))
volume.update()
end),
awful.button({}, 5, function() -- scroll down
os.execute(string.format("%s set %s 1%%-", volume.cmd, volume.channel))
volume.update()
end)
))
```
## Keybindings
Read [here](https://github.com/lcpz/lain/wiki/alsa#keybindings). If you want notifications, use `volume.notify()` instead of `volume.update()`.

100
awesome/lain/wiki/bat.md Normal file
View file

@ -0,0 +1,100 @@
## Usage
[Read here.](https://github.com/lcpz/lain/wiki/Widgets#usage)
### Description
Shows the remaining time and percentage capacity of your laptop battery, as well
as the current wattage. Multiple batteries are supported.
Displays a notification when battery is fully charged, low, or critical.
```lua
local mybattery = lain.widget.bat()
```
## Input table
Variable | Meaning | Type | Default
--- | --- | --- | ---
`timeout` | Refresh timeout (in seconds) | integer | 30
`pspath` | Power supply directory path | string | "/sys/class/power_supply/"
`battery` | Single battery id | string | autodetected
`batteries` | Multiple batteries id table | table of strings | autodetected
`ac` | AC | string | autodetected
`notify` | Show notification popups | string | "on"
`full_notify` | Show a notification popup when the battery's fully charged | string | inherited value from `notify`
`n_perc` | Percentages assumed for critical and low battery levels | table of integers | `{5, 15}`
`settings` | User settings | function | empty function
The widget will try to autodetect `battery`, `batteries` and `ac`. If something
goes wrong, you will have to define them manually. In that case, you only have
to define one between `battery` and `batteries`. If you have one battery, you
can either use `args.battery = "BAT*"` or `args.batteries = {"BAT*"}`, where `BAT*`
is the identifier of your battery in `pspath` (do not use it as a wildcard).
Of course, if you have multiple batteries, you need to use the latter option.
To disable notifications, set `notify` to `"off"`.
If you define `pspath`, **be sure** to not forget the final slash (/).
`settings` can use the `bat_now` table, which contains the following strings:
- `status`, general status ("N/A", "Discharging", "Charging", "Full");
- `n_status[i]`, i-th battery status (like above);
- `ac_status`, AC-plug flag (0 if cable is unplugged, 1 if plugged, "N/A" otherwise);
- `perc`, total charge percentage (integer between 0 and 100 or "N/A");
- `n_perc[i]`, i-th battery charge percentage (like above);
- `time`, time remaining until charge if charging, until discharge if discharging (HH:MM string or "N/A");
- `watt`, battery watts (float with 2 decimals).
and can modify the following three tables, which will be the preset for the naughty notifications:
* `bat_notification_charged_preset` (used if battery is fully charged and connected to AC)
* `bat_notification_low_preset` (used if battery charge level <= 15)
* `bat_notification_critical_preset` (used if battery charge level <= 5)
Check [here](https://awesomewm.org/doc/api/libraries/naughty.html#notify) for
the list of variables they can contain. Default definitions:
```lua
bat_notification_charged_preset = {
title = "Battery full",
text = "You can unplug the cable",
timeout = 15,
fg = "#202020",
bg = "#CDCDCD"
}
```
```lua
bat_notification_low_preset = {
title = "Battery low",
text = "Plug the cable!",
timeout = 15,
fg = "#202020",
bg = "#CDCDCD"
}
```
```lua
bat_notification_critical_preset = {
title = "Battery exhausted",
text = "Shutdown imminent",
timeout = 15,
fg = "#000000",
bg = "#FFFFFF"
}
```
## Output table
Variable | Meaning | Type
--- | --- | ---
`widget` | The widget | `wibox.widget.textbox`
`update` | Update `widget` | function
The `update` function can be used to refresh the widget before `timeout` expires.
## Note
Alternatively, you can try the [`upower` recipe](https://awesomewm.org/recipes/watch).

83
awesome/lain/wiki/cal.md Normal file
View file

@ -0,0 +1,83 @@
## Usage
[Read here.](https://github.com/lcpz/lain/wiki/Widgets#usage)
### Description
Creates a calendar notification that can be attached to widgets.
This is a simpler but [faster](https://github.com/awesomeWM/awesome/issues/1861)
alternative to [`awful.widget.calendar_popup`](https://awesomewm.org/doc/api/classes/awful.widget.calendar_popup.html), which emulates UNIX's `cal`.
```lua
local mycal = lain.widget.cal()
```
## Input table
Variable | Meaning | Type | Default
--- | --- | --- | ---
`attach_to` | List of widgets | table | empty table
`week_start` | First day of the week | integer | 2 (Monday)
`three` | Display three months spanning the date | boolean | false
`followtag` | Display the notification on currently focused screen | boolean | false
`week_number` | Display the week number | string ("none", "left" or "right") | "none"
`week_number_format` | Week number format | string | `"%3d \| "` for "left", `"\| %-3d"` for "right"
`icons` | Path to calendar icons | string | [icons/cal/white/](https://github.com/lcpz/lain/tree/master/icons/cal/white)
`notification_preset` | Notification preset | table | See [default `notification_preset`](https://github.com/lcpz/lain/wiki/calendar#default-notification_preset)
Set `attach_to` as the list of widgets to which you want to attach the calendar, like this:
```lua
local mycal = lain.widget.cal {
attach_to = { mywidget1, mywidget2, ... },
-- [...]
}
```
For every widget in `attach_to`:
- Left click / scroll down: switch to previous month.
- Middle click show current month.
- Right click / scroll up: switch to next month.
With multiple screens, the default behaviour is to show a visual notification pop-up window on the first screen. By setting `followtag` to `true` it will be shown on the currently focused tag screen.
### Default `notification_preset`
```lua
notification_preset = {
font = "Monospace 10",
fg = "#FFFFFF",
bg = "#000000"
}
```
## Output table
Variable | Meaning | Type
--- | --- | ---
`attach` | Attach the calendar to an input widget | function
`show` | Show calendar | function
`hide` | Hide calendar | function
`attach` takes as argument any widget you want to attach the calendar to, while
`show` takes as optional argument an integer to indicate the seconds to timeout.
## Keybinding
```lua
awful.key({ altkey }, "c", function () mycal.show(7) end)
```
Where `altkey = "Mod1"`.
## Notes
* Naughty notifications require `notification_preset.font` to be **monospaced**, in order to correctly display the output.
* If you want to [disable notification icon](https://github.com/lcpz/lain/pull/351), set `icons = ""` in the input table.
* If you want to localise the calendar, put `os.setlocale(os.getenv("LANG"))` in your `rc.lua`.
* If you want to get notifications [only with mouse clicks](https://github.com/lcpz/lain/issues/320) on a given widget, use this code:
```lua
yourwidget:disconnect_signal("mouse::enter", mycal.hover_on)
```

30
awesome/lain/wiki/cpu.md Normal file
View file

@ -0,0 +1,30 @@
## Usage
[Read here.](https://github.com/lcpz/lain/wiki/Widgets#usage)
### Description
Shows the current CPU usage, both in general and per core.
```lua
local mycpu = lain.widget.cpu()
```
## Input table
Variable | Meaning | Type | Default
--- | --- | --- | ---
`timeout` | Refresh timeout (in seconds) | integer | 2
`settings` | User settings | function | empty function
`settings` can use these strings:
* `cpu_now.usage`, the general use percentage;
* `cpu_now[i].usage`, the i-th core use percentage, with `i` starting from 1.
## Output table
Variable | Meaning | Type
--- | --- | ---
`widget` | The widget | `wibox.widget.textbox`
`update` | Update `widget` | function

82
awesome/lain/wiki/fs.md Normal file
View file

@ -0,0 +1,82 @@
## Usage
[Read here.](https://github.com/lcpz/lain/wiki/Widgets#usage)
### Description
Shows file systems informations.
If a partition is given in input, a notification will be displayed when it is almost full.
```lua
local mypartition = lain.widget.fs()
```
## Input table
Variable | Meaning | Type | Default
--- | --- | --- | ---
`timeout` | Refresh timeout (in seconds) | integer | 600
`partition` | (Optional) Partition to watch: a notification will be displayed when full | string | `nil`
`threshold` | Percentage threshold at which the notification is triggered | integer | 99
`notification_preset` | Notification preset | table | See [default `notification_preset`](https://github.com/lcpz/lain/wiki/fs#default-notification_preset)
`followtag` | Display the notification on currently focused screen | boolean | false
`showpopup` | Display popups with mouse hovering | string, possible values: "on", "off" | "on"
`settings` | User settings | function | empty function
`settings` can use the table `fs_now`, which contains a string entry for each file system path available. For instance, root infos are located in the variable `fs_now["/"]`. Every entry in this table have the following variables:
Variable | Meaning | Type
--- | --- | ---
`units` | (multiple of) units used | string ("Kb", "Mb", "Gb", and so on)
`percentage` | the used percentage | integer
`size` | size in `units` of the given fs | float
`used` | amount of space used in the given fs, expressed in `units` | float
`free` | amount of free space in the given fs, expressed in `units` | float
Usage example:
```lua
-- shows used (percentage) and remaining space in home partition
local fsroothome = lain.widget.fs({
settings = function()
widget:set_text("/home: " .. fs_now["/home"].percentage .. "% (" ..
fs_now["/home"].free .. " " .. fs_now["/home"].units .. " left)")
end
})
-- output example: "/home: 37% (239.4 Gb left)"
```
With multiple screens, the default behaviour is to show a visual notification pop-up window on the first screen. By setting `followtag` to `true` it will be shown on the currently focused tag screen.
### Default `notification_preset`
```lua
notification_preset = {
font = "Monospace 10",
fg = "#FFFFFF",
bg = "#000000"
}
```
## Output table
Variable | Meaning | Type
--- | --- | ---
`widget` | The widget | `wibox.widget.textbox`
`show` | The notification | function
You can display the notification with a key binding like this:
```lua
awful.key({ altkey }, "h", function () mypartition.show(seconds, scr) end),
```
where ``altkey = "Mod1"`` and ``show`` arguments, both optionals, are:
* `seconds`, notification time in seconds
* `scr`, screen which to display the notification in
## Note
Naughty notifications require `notification_preset.font` to be **monospaced**, in order to correctly display the output.

115
awesome/lain/wiki/imap.md Normal file
View file

@ -0,0 +1,115 @@
## Usage
[Read here.](https://github.com/lcpz/lain/wiki/Widgets#usage)
### Description
Shows mails count fetching over IMAP.
```lua
local myimap = lain.widget.imap(args)
```
New mails are notified like this:
+--------------------------------------------+
| +---+ |
| |\ /| donald@disney.org has 3 new messages |
| +---+ |
+--------------------------------------------+
## Input table
Required parameters are:
Variable | Meaning | Type
--- | --- | ---
`server` | Mail server | string
`mail` | User mail | string
`password` | User password | string
while the optional are:
Variable | Meaning | Type | Default
--- | --- | --- | ---
`port` | IMAP port | integer | 993
`timeout` | Refresh timeout (in seconds) | integer | 60
`pwdtimeout` | Timeout for password retrieval function (see [here](https://github.com/lcpz/lain/wiki/imap#password-security)) | integer | 10
`is_plain` | Define whether `password` is a plain password (true) or a command that retrieves it (false) | boolean | false
`followtag` | Notification behaviour | boolean | false
`notify` | Show notification popups | string | "on"
`settings` | User settings | function | empty function
`settings` can use `imap_now` table, which contains the following non negative integers:
- `["MESSAGES"]`
- `["RECENT"]`
- `["UNSEEN"]`
example of fetch: `total = imap_now["MESSAGES"]`. For backwards compatibility, `settings` can also use `mailcount`, a pointer to `imap_now["UNSEEN"]`.
Also, `settings` can modify `mail_notification_preset` table, which will be the preset for the naughty notifications. Check [here](https://awesomewm.org/apidoc/libraries/naughty.html#notify) for the list of variables it can contain. Default definition:
```lua
mail_notification _preset = {
icon = "lain/icons/mail.png",
position = "top_left"
}
```
Note that `mailcount` and `imap_now` elements are equals to 0 either if there are no new mails or credentials are invalid, so make sure that your settings are correct.
With multiple screens, the default behaviour is to show a visual notification pop-up window on the first screen. By setting `followtag` to `true` it will be shown on the currently focused tag screen.
You can have multiple instances of this widget at the same time.
## Password security
The reason why `is_plain` is false by default is to discourage the habit of storing passwords in plain.
In general, when `is_plain == false`, `password` can be either a string, a table or a function: the widget will execute it asynchronously in the first two cases.
### Using plain passwords
You can set your password in plain like this:
```lua
myimapcheck = lain.widget.imap {
is_plain = true,
password = "mymailpassword",
-- [...]
}
```
and you will have the same security provided by `~/.netrc`.
### Using a password manager
I recommend to use [spm](https://notabug.org/kl3/spm) or [pass](https://www.passwordstore.org). In this case, `password` has to be a function. Example stub:
```lua
myimapcheck = lain.widget.imap {
password = function()
-- do your retrieval
return retrieved_password, try_again
end,
-- [...]
}
```
Where `retrieved_password` is the password retrieved from the manager, and `try_again` supports [DBus Secret Service](https://specifications.freedesktop.org/secret-service).
The process flow is that the first `password()` call spawns the unlock prompt, then the second call retrieves the password. [Here](https://gist.github.com/lcpz/1854fc4320f4701957cd5309c8eed4a6) is an example of `password` function.
## Output table
Variable | Meaning | Type
--- | --- | ---
`widget` | The widget | `wibox.widget.textbox`
`update` | Update `widget` | function
`timer` | The widget timer | [`gears.timer`](https://awesomewm.org/doc/api/classes/gears.timer.html)
`pwdtimer` | Password retrieval timer (available only if `password` is a function)| [`gears.timer`](https://awesomewm.org/doc/api/classes/gears.timer.html)
The `update` function can be used to refresh the widget before `timeout` expires.
You can use `timer` to start/stop the widget as you like.

33
awesome/lain/wiki/mem.md Normal file
View file

@ -0,0 +1,33 @@
## Usage
[Read here.](https://github.com/lcpz/lain/wiki/Widgets#usage)
### Description
Shows memory status in MiB, [like `top` and `free -h`](https://github.com/lcpz/lain/issues/271).
```lua
local mymem = lain.widget.mem()
```
## Input table
Variable | Meaning | Type | Default
--- | --- | --- | ---
`timeout` | Refresh timeout (in seconds) | integer | 2
`settings` | User settings | function | empty function
in `settings` you can use the following variables:
Variable | Meaning | Type
--- | --- | ---
`mem_now.used` | Memory used (MiB) | string
`mem_now.swapused` | Swap memory used (MiB) | string
`mem_now.perc` | Memory percentage | int
## Output table
Variable | Meaning | Type
--- | --- | ---
`widget` | The widget | `wibox.widget.textbox`
`update` | Update `widget` | function

122
awesome/lain/wiki/moc.md Normal file
View file

@ -0,0 +1,122 @@
## Usage
[Read here.](https://github.com/lcpz/lain/wiki/Widgets#usage)
### Description
A widget for showing the current song track's information from MOC (Music On Console).
```lua
local mymoc = lain.widget.contrib.moc()
```
Now playing songs are notified like this:
+--------------------------------------------------------+
| +-------+ |
| |/^\_/^\| Now playing |
| |\ O O /| Cannibal Corpse (Hammer Smashed Face) - 1993 |
| | '.o.' | Hammer Smashed Face (Radio Disney Version) |
| +-------+ |
+--------------------------------------------------------+
## Input table
Variable | Meaning | Type | Default
--- | --- | --- | ---
`timeout` | Refresh timeout (in seconds) | integer | 1
`music_dir` | Music directory | string | "~/Music"
`cover_size` | Album art notification size (both height and width) | integer | 100
`cover_pattern` | Pattern for the album art file | string | `*\\.(jpg|jpeg|png|gif)`*
`default_art` | Default art | string | ""
`followtag` | Display the notification on currently focused screen | boolean | false
`settings` | User settings | function | empty function
\* In Lua, "\\\\" means "\" escaped.
Default `cover_pattern` definition will made the widget set the first jpg, jpeg, png or gif file found in the directory as the album art.
Pay attention to case sensitivity when defining `music_dir`.
`settings` can use `moc_now` table, which contains the following string values:
- state (possible values: "PLAY", "PAUSE", "STOP")
- file
- artist
- title
- album
- elapsed (Time elapsed for the current track)
- total (The current track's total time)
and can modify `moc_notification_preset` table, which will be the preset for the naughty notifications. Check [here](https://awesomewm.org/apidoc/libraries/naughty.html#notify) for the list of variables it can contain. Default definition:
```lua
moc_notification_preset = {
title = "Now playing",
timeout = 6,
text = string.format("%s (%s) - %s\n%s", moc_now.artist,
moc_now.album, moc_now.elapsed, moc_now.title)
}
```
With multiple screens, the default behaviour is to show a visual notification pop-up window on the first screen. By setting `followtag` to `true` it will be shown on the currently focused tag screen.
## Output table
Variable | Meaning | Type
--- | --- | ---
`widget` | The widget | `wibox.widget.textbox`
`update` | Update `widget` | function
`timer` | The widget timer | [`gears.timer`](https://awesomewm.org/doc/api/classes/gears.timer.html)
The `update` function can be used to refresh the widget before `timeout` expires.
You can use `timer` to start/stop the widget as you like.
## Keybindings
You can control the widget with key bindings like these:
```lua
-- MOC control
awful.key({ altkey, "Control" }, "Up",
function ()
os.execute("mocp -G") -- toggle
moc.update()
end),
awful.key({ altkey, "Control" }, "Down",
function ()
os.execute("mocp -s") -- stop
moc.update()
end),
awful.key({ altkey, "Control" }, "Left",
function ()
os.execute("mocp -r") -- previous
moc.update()
end),
awful.key({ altkey, "Control" }, "Right",
function ()
os.execute("mocp -f") -- next
moc.update()
end),
```
where `altkey = "Mod1"`.
If you don't use the widget for long periods and wish to spare CPU, you can toggle it with a keybinding like this:
```lua
-- toggle MOC widget
awful.key({ altkey }, "0",
function ()
local common = { text = "MOC widget ", position = "top_middle", timeout = 2 }
if moc.timer.started then
moc.timer:stop()
common.text = common.text .. markup.bold("OFF")
else
moc.timer:start()
common.text = common.text .. markup.bold("ON")
end
naughty.notify(common)
end),
```

180
awesome/lain/wiki/mpd.md Normal file
View file

@ -0,0 +1,180 @@
## Usage
[Read here.](https://github.com/lcpz/lain/wiki/Widgets#usage)
### Description
Shows MPD status.
```lua
local mympd = lain.widget.mpd()
```
Now playing songs are notified like this:
+--------------------------------------------------------+
| +-------+ |
| |/^\_/^\| Now playing |
| |\ O O /| Cannibal Corpse (Hammer Smashed Face) - 1993 |
| | '.o.' | Hammer Smashed Face (Radio Disney Version) |
| +-------+ |
+--------------------------------------------------------+
**Note:** if MPD is turned off or not set correctly, the widget will constantly display "N/A" values.
## Input table
Variable | Meaning | Type | Default
--- | --- | --- | ---
`timeout` | Refresh timeout (in seconds) | integer | 2
`password` | MPD password | string | ""
`host` | MPD server | string | "127.0.0.1"
`port` | MPD port | string | "6600"
`music_dir` | Music directory | string | "~/Music"
`cover_size` | Album art notification size (both height and width) | integer | 100
`cover_pattern` | Pattern for the album art file | string | `*.(jpg\|jpeg\|png\|gif)$`
`default_art` | Default art | string | `nil`
`notify` | Show notification popups | string | "on"
`followtag` | Notification behaviour | boolean | false
`settings` | User settings | function | empty function
\* In Lua, "\\\\" means "\" escaped.
Default `cover_pattern` definition will made the widget set the first jpg, jpeg, png or gif file found in the directory as the album art.
Pay attention to case sensitivity when defining `music_dir`.
`settings` can use `mpd_now` table, which contains the following values:
(**note:** the first four are boolean [flags](https://github.com/lcpz/lain/pull/205), the remaining are all strings)
- random_mode
- single_mode
- repeat_mode
- consume_mode
- pls_pos (playlist position)
- pls_len (playlist length)
- state (possible values: "play", "pause", "stop")
- file
- artist
- title
- name
- album
- track
- genre
- date
- [time](https://github.com/lcpz/lain/pull/90) (length of current song, in seconds)
- [elapsed](https://github.com/lcpz/lain/pull/90) (elapsed time of current song, in seconds)
and can modify `mpd_notification_preset` table, which will be the preset for the naughty notifications. Check [here](https://awesomewm.org/doc/api/libraries/naughty.html#notify) for the list of variables it can contain. Default definition:
```lua
mpd_notification_preset = {
title = "Now playing",
timeout = 6,
text = string.format("%s (%s) - %s\n%s", mpd_now.artist,
mpd_now.album, mpd_now.date, mpd_now.title)
}
```
With multiple screens, the default behaviour is to show a visual notification pop-up window on the first screen. By setting `followtag` to `true` it will be shown on the currently focused tag screen.
## Output table
Variable | Meaning | Type
--- | --- | ---
`widget` | The textbox | `wibox.widget.textbox`
`update` | Update `widget` | function
`timer` | The widget timer | [`gears.timer`](https://awesomewm.org/doc/api/classes/gears.timer.html)
The `update` function can be used to refresh the widget before `timeout` expires.
You can use `timer` to start/stop the widget as you like.
## Keybindings
You can control the widget with keybindings like these:
```lua
-- MPD control
awful.key({ altkey, "Control" }, "Up",
function ()
awful.spawn.with_shell("mpc toggle || ncmpc toggle || pms toggle")
mympd.update()
end),
awful.key({ altkey, "Control" }, "Down",
function ()
awful.spawn.with_shell("mpc stop || ncmpc stop || pms stop")
mympd.update()
end),
awful.key({ altkey, "Control" }, "Left",
function ()
awful.spawn.with_shell("mpc prev || ncmpc prev || pms prev")
mympd.update()
end),
awful.key({ altkey, "Control" }, "Right",
function ()
awful.spawn.with_shell("mpc next || ncmpc next || pms next")
mympd.update()
end),
```
where `altkey = "Mod1"`.
If you don't use the widget for long periods and wish to spare CPU, you can toggle it with a keybinding like this:
```lua
-- disable MPD widget
awful.key({ altkey }, "0",
function ()
local common = {
text = "MPD widget ",
position = "top_middle",
timeout = 2
}
if mympd.timer.started then
mympd.timer:stop()
common.text = common.text .. markup.bold("OFF")
else
mympd.timer:start()
common.text = common.text .. markup.bold("ON")
end
naughty.notify(common)
end),
```
## Notes
### Cover not showing in notifications
If the cover file is existent but not showed in notifications, [try](https://github.com/lcpz/lain/issues/393) setting `music_dir` to a symlink of your music folder, rather than to a physical path. This can be easily done through
```shell
ln -s /the/real_path_to_your_music/ /home/username/Music
```
However, this only applies if the music is stored outside your user-specific folder, for instance in an external partition.
### Always use `set_markup`
In `settings`, if you use `widget:set_text`, [it will ignore Pango markup](https://github.com/lcpz/lain/issues/258), so be sure to always use `widget:set_markup`.
### Volume fade in toggling MPD
If you want a fade in/out in toggling MPD, you can put [this script](https://gist.github.com/lcpz/76e315bc27c6cdf7edd5021964b88df1) in your local `bin` directory:
```shell
$ curl https://gist.githubusercontent.com/lcpz/76e315bc27c6cdf7edd5021964b88df1/raw/97f7ba586418a4e07637cfbc91d2974278dfa623/mpd-fade -o ~/bin/mpc-fade
$ chmod +x ~/bin/mpc-fade
```
Set your 1% decrease/increase commands [here](https://gist.github.com/lcpz/76e315bc27c6cdf7edd5021964b88df1#file-mpd-fade-L8-L9), then use a keybinding like this:
```lua
-- MPD toggle with volume fading
awful.key({ "Shift" }, "Pause",
function()
awful.spawn.easy_async("mpc-fade 20 4", -- mpc-fade <percentage> <length in secs>
function(stdout, stderr, reason, exit_code)
mympd.update()
end)
end),
```

115
awesome/lain/wiki/net.md Normal file
View file

@ -0,0 +1,115 @@
## Usage
[Read here.](https://github.com/lcpz/lain/wiki/Widgets#usage)
### Description
Monitors network interfaces and shows current traffic.
```lua
local mynet = lain.widget.net()
```
## Input table
Variable | Meaning | Type | Default
--- | --- | --- | ---
`timeout` | Refresh timeout (in seconds) | integer | 2
`iface` | Network device(s) | string (single interface) or table of strings (multiple interfaces) | autodetected
`units` | Units | integer | 1024 (kilobytes)
`notify` | Display "no carrier" notifications | string | "on"
`wifi_state` | Get wifi connection status | string | "off"
`eth_state` | Get ethernet connection status | string | "off"
`screen` | Notifications screen | integer | 1
`settings` | User settings | function | empty function
`iface` can be a string or an table of the form `{ "eth0", "eth1", ... }` containing a list of the devices to collect data on.
If more than one device is included, `net_now.sent` and `net_now.received` will contain cumulative values over all given devices.
Use `net_now.devices["eth0"]` to access `sent`, `received`, `state` or `carrier` per device.
Possible alternative values for `units` are 1 (byte) or multiple of 1024: 1024^2 (mb), 1024^3 (gb), and so on.
If `notify = "off"` is set, the widget won't display a notification when there's no carrier.
`settings` can use the following `iface` related strings:
- `net_now.carrier` ("0", "1");
- `net_now.state` ("up", "down");
- `net_now.sent` and `net_now.received` (numbers) will be the sum across all specified interfaces;
- `net_now.devices["interface"]` contains the same attributes as the old api for each interface. More on this in the "Multiple devices" section below.
If `wifi_state = "on"` is set, `settings` can use the following extra strings attached to `net_now.devices["wireless interface"]`:
- `wifi` (true, false) indicates if the interface is connected to a network;
- `signal` (number) is the connection signal strength in dBm;
If `eth_state = "on"` is set, `settings` can use the following extra string: `net_now.devices["ethernet interface"].ethernet`, which is a boolean indicating if an ethernet connection's active.
For compatibility reasons, if multiple devices are given, `net_now.carrier` and `net_now.state` correspond to the last interface in the iface table and should not be relied upon (deprecated).
## Output table
Variable | Meaning | Type
--- | --- | ---
`widget` | The widget | `wibox.widget.textbox`
`update` | Update `widget` | function
## Notes
### Setting `iface` manually
If the widget [spawns a "no carrier" notification and you are sure to have an active network device](https://github.com/lcpz/lain/issues/102), then autodetection is probably not working. This may due to [your user privileges](https://github.com/lcpz/lain/issues/102#issuecomment-246470526). In this case you can set `iface` manually. You can see which device is **UP,LOWER_UP** with the following command:
```shell
ip link show
```
## Usage examples
### Two widgets for upload/download rates from the same `iface`
```lua
local mynetdown = wibox.widget.textbox()
local mynetup = lain.widget.net {
settings = function()
widget:set_markup(net_now.sent)
netdowninfo:set_markup(net_now.received)
end
}
```
### Wifi connection + signal strength indicator and ethernet connection indicator
```lua
local wifi_icon = wibox.widget.imagebox()
local eth_icon = wibox.widget.imagebox()
local net = lain.widget.net {
notify = "off",
wifi_state = "on",
eth_state = "on",
settings = function()
local eth0 = net_now.devices.eth0
if eth0 then
if eth0.ethernet then
eth_icon:set_image(ethernet_icon_filename)
else
eth_icon:set_image()
end
end
local wlan0 = net_now.devices.wlan0
if wlan0 then
if wlan0.wifi then
local signal = wlan0.signal
if signal < -83 then
wifi_icon:set_image(wifi_weak_filename)
elseif signal < -70 then
wifi_icon:set_image(wifi_mid_filename)
elseif signal < -53 then
wifi_icon:set_image(wifi_good_filename)
elseif signal >= -53 then
wifi_icon:set_image(wifi_great_filename)
end
else
wifi_icon:set_image()
end
end
end
}
```

135
awesome/lain/wiki/pulse.md Normal file
View file

@ -0,0 +1,135 @@
## Usage
[Read here.](https://github.com/lcpz/lain/wiki/Widgets#usage)
### Description
Shows and controls PulseAudio volume.
```lua
local volume = lain.widget.pulse()
```
## Input table
Variable | Meaning | Type | Default
--- | --- | --- | ---
`timeout` | Refresh timeout (in seconds) | integer | 5
`devicetype` | PulseAudio device type | string ("sink", "source") | "sink"
`cmd` | PulseAudio command | string or function | see [here](https://github.com/lcpz/lain/blob/master/widget/pulse.lua#L26)
`settings` | User settings | function | empty function
`cmd` is a terminal command to catch infos from current default device. You can redefine it, being sure that the ouput is something like this:
```shell
* index: 0
volume: front-left: 18340 / 28% / -33.18 dB, front-right: 18340 / 28% / -33.18 dB
muted: no
device.string = "front:1"
```
If your devices change dynamically, you can define it as a function which returns a command string.
If sed doesn't work, you can try with a grep variant:
```lua
cmd = "pacmd list-" .. pulse.devicetype .. "s | grep -e $(pactl info | grep -e 'ink' | cut -d' ' -f3) -e 'volume: front' -e 'muted'"
```
### `settings` variables
`settings` can use the following variables:
Variable | Meaning | Type | Values
--- | --- | --- | ---
`volume_now.device` | Device name | string | device name or "N/A"
`volume_now.index` | Device index | string | >= "0"
`volume_now.muted` | Device mute status | string | "yes", "no", "N/A"
`volume_now.channel` | Device channels | table of string integers | `volume_now.channel[i]`, where `i >= 1`
`volume_now.left` | Front left sink level or first source | string | "0"-"100"
`volume_now.right` | Front right sink level or second source | string | "0"-"100"
`volume_now.channel` is a table of your PulseAudio devices. Fetch a channel level like this: `volume_now.channel[i]`, where `i >= 1`.
`volume_now.{left,right}` are pointers for `volume_now.{channel[1], channel[2]}` (stereo).
## Output table
Variable | Meaning | Type
--- | --- | ---
`widget` | The widget | `wibox.widget.textbox`
`update` | Update `widget` | function
## Buttons
```lua
volume.widget:buttons(awful.util.table.join(
awful.button({}, 1, function() -- left click
awful.spawn("pavucontrol")
end),
awful.button({}, 2, function() -- middle click
os.execute(string.format("pactl set-sink-volume %d 100%%", volume.device))
volume.update()
end),
awful.button({}, 3, function() -- right click
os.execute(string.format("pactl set-sink-mute %d toggle", volume.device))
volume.update()
end),
awful.button({}, 4, function() -- scroll up
os.execute(string.format("pactl set-sink-volume %d +1%%", volume.device))
volume.update()
end),
awful.button({}, 5, function() -- scroll down
os.execute(string.format("pactl set-sink-volume %d -1%%", volume.device))
volume.update()
end)
))
```
## Keybindings
```lua
-- PulseAudio volume control
awful.key({ altkey }, "Up",
function ()
os.execute(string.format("pactl set-sink-volume %d +1%%", volume.device))
volume.update()
end),
awful.key({ altkey }, "Down",
function ()
os.execute(string.format("pactl set-sink-volume %d -1%%", volume.device))
volume.update()
end),
awful.key({ altkey }, "m",
function ()
os.execute(string.format("pactl set-sink-mute %d toggle", volume.device))
volume.update()
end),
awful.key({ altkey, "Control" }, "m",
function ()
os.execute(string.format("pactl set-sink-volume %d 100%%", volume.device))
volume.update()
end),
awful.key({ altkey, "Control" }, "0",
function ()
os.execute(string.format("pactl set-sink-volume %d 0%%", volume.device))
volume.update()
end),
```
where `altkey = "Mod1"`.
## Example
```lua
-- PulseAudio volume (based on multicolor theme)
local volume = lain.widget.pulse {
settings = function()
vlevel = volume_now.left .. "-" .. volume_now.right .. "% | " .. volume_now.device
if volume_now.muted == "yes" then
vlevel = vlevel .. " M"
end
widget:set_markup(lain.util.markup("#7493d2", vlevel))
end
}
```

94
awesome/lain/wiki/pulsebar.md Normal file
View file

@ -0,0 +1,94 @@
## Usage
[Read here.](https://github.com/lcpz/lain/wiki/Widgets#usage)
### Description
Shows PulseAudio volume with a progressbar; provides tooltips and notifications.
```lua
local volume = lain.widget.pulsebar()
```
## Input table
Variable | Meaning | Type | Default
--- | --- | --- | ---
`timeout` | Refresh timeout (in seconds) | integer | 5
`settings` | User settings | function | empty function
`width` | Bar width | number | 63
`height` | Bar height | number | 1
`margins` | Bar margins | number | 1
`paddings` | Bar paddings | number | 1
`ticks` | Set bar ticks on | boolean | false
`ticks_size` | Ticks size | number | 7
`scallback` | [PulseAudio sink callback](https://github.com/lcpz/lain/wiki/pulseaudio/) | function | `nil`
`sink` | Mixer sink | number | 0
`colors` | Bar colors | table | see [Default colors](https://github.com/lcpz/lain/wiki/pulsebar#default-colors)
`notification_preset` | Notification preset | table | See [default `notification_preset`](https://github.com/lcpz/lain/wiki/pulsebar#default-notification_preset)
`followtag` | Display the notification on currently focused screen | boolean | false
`notification_preset` | Notification preset | table | See [default `notification_preset`](https://github.com/lcpz/lain/wiki/pulsebar#default-notification_preset)
`devicetype` | PulseAudio device type | string ("sink", "source") | "sink"
`cmd` | PulseAudio command | string or function | see [here](https://github.com/lcpz/lain/blob/master/widget/pulsebar.lua#L48)
Read [pulse](https://github.com/lcpz/lain/wiki/pulse) page for `cmd` settings.
`settings` can use [these variables](https://github.com/lcpz/lain/wiki/pulse#settings-variables).
With multiple screens, the default behaviour is to show a visual notification pop-up window on the first screen. By setting `followtag` to `true` it will be shown on the currently focused tag screen.
### Default colors
Variable | Meaning | Type | Default
--- | --- | --- | ---
`background` | Bar backgrund color | string | "#000000"
`mute` | Bar mute color | string | "#EB8F8F"
`unmute` | Bar unmute color | string | "#A4CE8A"
### Default `notification_preset`
```lua
notification_preset = {
font = "Monospace 10"
}
```
## Output table
Variable | Meaning | Type
--- | --- | ---
`bar` | The widget | `wibox.widget.progressbar`
`device` | PulseAudio device | string
`notify` | The notification | function
`update` | Update state | function
`tooltip` | The tooltip | `awful.tooltip`
## Buttons
```lua
volume.bar:buttons(awful.util.table.join(
awful.button({}, 1, function() -- left click
awful.spawn("pavucontrol")
end),
awful.button({}, 2, function() -- middle click
os.execute(string.format("pactl set-sink-volume %d 100%%", volume.device))
volume.update()
end),
awful.button({}, 3, function() -- right click
os.execute(string.format("pactl set-sink-mute %d toggle", volume.device))
volume.update()
end),
awful.button({}, 4, function() -- scroll up
os.execute(string.format("pactl set-sink-volume %d +1%%", volume.device))
volume.update()
end),
awful.button({}, 5, function() -- scroll down
os.execute(string.format("pactl set-sink-volume %d -1%%", volume.device))
volume.update()
end)
))
```
## Keybindings
Same as [here](https://github.com/lcpz/lain/wiki/pulse#keybindings). If you want notifications, use `volume.notify()` instead of `volume.update()`.

100
awesome/lain/wiki/redshift.md Normal file
View file

@ -0,0 +1,100 @@
### What is Redshift? #
[**Project homepage**](http://jonls.dk/redshift/)
>**Redshift** is an application that adjusts the computer display's color temperature based upon the Sun's apparent position in relation to the user's location on Earth.
>
>The program is free software, inspired by the proprietary f.lux, and can be used to reduce eye strain as well as insomnia and delayed sleep phase syndrome.
>
>The computer display's color temperature transitions evenly from night to daytime temperature to allow the user's eyes to slowly adapt. At night, the color temperature is low and is typically 3000–4000 K (default is 3500 K), preferably matching the room's lighting temperature. Typical color temperature during the daytime is 5500–6500 K (default is 5500 K).
**Source:** [Wikipedia](https://en.wikipedia.org/wiki/Redshift_%28software%29)
### Preparations
**Redshift must be installed** on your system if you want to use this widget.
Packages should be available for most distributions. Source code and build instructions can be found on Github [here](https://github.com/jonls/redshift).
You also need a valid config file. Please see the [project homepage](http://jonls.dk/redshift/) for details. An example: [`~/.config/redshift.conf`](https://github.com/jonls/redshift/blob/master/redshift.conf.sample).
You have to match the location settings to your personal situation: you can adjust the `lat` and `lon` variables using a [web service](https://encrypted.google.com/search?q=get+latitude+and+longitude).
You might also want to modify the color temperatures to fit your preferences.
### Using the widget
This widget provides the following functions:
| function | meaning |
| --- | --- |
| `redshift:toggle()` | Toggles Redshift adjustments on or off, and also restarts it if terminates. |
| `redshift:attach(widget, update_function)` | Attach to a widget. Click on the widget to toggle redshift on or off. `update_function` is a callback function which will be triggered each time Redshift changes its status. (See the examples below.) |
### Usage examples
#### Textbox status widget
```lua
myredshift = wibox.widget.textbox()
lain.widget.contrib.redshift:attach(
myredshift,
function (active)
if active then
myredshift:set_text("RS on")
else
myredshift:set_text("RS off")
end
end
)
```
Then add `myredshift.widget` to your wibox.
#### Checkbox status widget
```lua
local markup = lain.util.markup
local myredshift = wibox.widget{
checked = false,
check_color = "#EB8F8F",
border_color = "#EB8F8F",
border_width = 1,
shape = gears.shape.square,
widget = wibox.widget.checkbox
}
local myredshift_text = wibox.widget{
align = "center",
widget = wibox.widget.textbox,
}
local myredshift_stack = wibox.widget{
myredshift,
myredshift_text,
layout = wibox.layout.stack
}
lain.widget.contrib.redshift:attach(
myredshift,
function (active)
if active then
myredshift_text:set_markup(markup(beautiful.bg_normal, "<b>R</b>"))
else
myredshift_text:set_markup(markup(beautiful.fg_normal, "R"))
end
myredshift.checked = active
end
)
```
Then add the `myredshift_stack` widget to your wibox.
#### Keybinding
Add this to the keybindings in your `rc.lua`:
```lua
-- Toggle redshift with Mod+Shift+t
awful.key({ modkey, "Shift" }, "t", function () lain.widget.contrib.redshift:toggle() end),
```

27
awesome/lain/wiki/sysload.md Normal file
View file

@ -0,0 +1,27 @@
## Usage
[Read here.](https://github.com/lcpz/lain/wiki/Widgets#usage)
### Description
Shows the current system load.
```lua
mysysload = lain.widget.sysload()
```
## Input table
Variable | Meaning | Type | Default
--- | --- | --- | ---
`timeout` | Refresh timeout (in seconds) | integer | 2
`settings` | User settings | function | empty function
`settings` can use strings `load_1`, `load_5` and `load_15`, which are the load averages over 1, 5, and 15 minutes.
## Output table
Variable | Meaning | Type
--- | --- | ---
`widget` | The widget | `wibox.widget.textbox`
`update` | Update `widget` | function

51
awesome/lain/wiki/task.md Normal file
View file

@ -0,0 +1,51 @@
## Usage
[Read here.](https://github.com/lcpz/lain/wiki/Widgets#usage)
### Description
Attaches a [taskwarrior](http://taskwarrior.org) notifications to a widget, and lets you execute `task` commands from the promptbox.
```lua
lain.widget.contrib.task.attach(widget, args)
```
`args` is an optional table which can contain:
Variable | Meaning | Type | Default
--- | --- | --- | ---
`show_cmd` | Taskwarrior command to show in the popup | string | "task next"
`prompt_text` | Prompt text | string | "Enter task command: "
`followtag` | Display the notification on currently focused screen | boolean | false
`notification_preset` | Notification preset | table | See [default `notification_preset`](https://github.com/lcpz/lain/wiki/task#default-notification_preset)
The tasks are shown in a notification popup when the mouse is moved over the attached `widget`, and the popup is hidden when the mouse is moved away. By default, the notification will show the output of `task next`. With `show_cmd`, the `task` popup command can be customized, for example if you want to [filter the tasks](https://taskwarrior.org/docs/filter.html) or show a [custom report](https://github.com/lcpz/lain/pull/213).
With multiple screens, the default behaviour is to show a visual notification pop-up window on the first screen. By setting `followtag` to `true` it will be shown on the currently focused tag screen.
You can call the notification with a keybinding like this:
```lua
awful.key({ modkey, altkey }, "t", function () lain.widget.contrib.task.show(scr) end),
```
where ``altkey = "Mod1"`` and `scr` (optional) indicates the screen which you want the notification in.
And you can prompt to input a `task` command with a keybinding like this:
```lua
awful.key({ altkey }, "t", lain.widget.contrib.task.prompt),
```
### Default `notification_preset`
```lua
notification_preset = {
font = "Monospace 10",
icon = helpers.icons_dir .. "/taskwarrior.png"
}
```
## Note
* If your widget does not display `task next` output, try changing Taskwarrior verbose, for instance: `show_cmd = 'task rc.verbose:label'` or `show_cmd = 'task rc.verbose:nothing'`.

35
awesome/lain/wiki/temp.md Normal file
View file

@ -0,0 +1,35 @@
## Usage
[Read here.](https://github.com/lcpz/lain/wiki/Widgets#usage)
### Description
Shows the current CPU temperature.
```lua
local mytemp = lain.widget.temp()
```
## Input table
Variable | Meaning | Type | Default
--- | --- | --- | ---
`timeout` | Refresh timeout (in seconds) | integer | 30
`tempfile` | Path of file which stores core temperature value | string | "/sys/devices/virtual/thermal/thermal_zone0/temp"
`settings` | User settings | function | empty function
`settings` can use the string `coretemp_now`, which contains the info retrieved from `tempfile`, and the table `temp_now`, which contains an entry for each `*temp*` file in each directory in the following paths:
```shell
/sys/class/devices/virtual/thermal/thermal_zone*
/sys/class/devices/platform/coretemp*/hwmon/hwon*
```
All values are expressed in Celsius (GNU/Linux standard).
## Output table
Variable | Meaning | Type
--- | --- | ---
`widget` | The widget | `wibox.widget.textbox`
`update` | Update `widget` | function

103
awesome/lain/wiki/tp_smapi.md Normal file
View file

@ -0,0 +1,103 @@
# Description
[`tp_smapi`](http://www.thinkwiki.org/wiki/Tp_smapi) interface and widget creator.
```lua
local tp_smapi = lain.widget.contrib.tp_smapi(apipath)
```
The argument `apipath` is an optional string which defines the API path. Its default value is `"/sys/devices/platform/smapi"`.
# Functions
## tp_smapi.get(batid, feature)
Gets the `feature` of battery `batid`. Returns a string. The list of available features is available at [this page](https://www.thinkwiki.org/wiki/Tp_smapi#Battery_status_features).
## tp_smapi.installed(batid)
Checks if battery `batid` is installed. Returns a boolean.
## tp_smapi.status(batid)
Gets the status of battery `batid`. Returns a string ("charging", "discharging", or "full").
## tp_smapi.percentage(batid)
Gets the percentage of battery `batid`. Returns a numeric string.
## tp_smapi.time(batid)
Gets the time of battery `batid`. Depending on the current status, it can be either running or charging time. Returns a string of the format `HH:MM`.
## tp_smapi.hide()
Removes any notification spawned by `tp_smapi.show`.
## tp_smapi.show(batid, seconds, scr)
Notifies the current information of battery `batid` for `seconds` seconds on screen `scr`.
The argument `scr` is optional, and if missing, the notification will be displayed on the currently focused screen.
## tp_smapi.create_widget(args)
Creates a [lain widget](https://github.com/lcpz/lain/wiki/Widgets#usage) of the available ThinkPad batteries.
```lua
local tpbat = tp_smapi.create_widget()
```
### Input table
Variable | Meaning | Type | Default
--- | --- | --- | ---
`widget` | The widget type to use | [`wibox.widget`](https://awesomewm.org/doc/api/classes/wibox.widget.html) | [`wibox.widget.textbox`](https://awesomewm.org/doc/api/classes/wibox.widget.textbox.html)
`timeout` | Refresh timeout (in seconds) | integer | 30
`pspath` | Power supply directory path | string | "/sys/class/power_supply/"
`battery` | Single battery id | string | autodetected
`batteries` | Multiple batteries id table | table of strings | autodetected
`settings` | User settings | function | empty function
The widget will try to autodetect `battery` and `batteries`. If something
goes wrong, you will have to define them manually. In that case, you only have
to define one between `battery` and `batteries`. If you have one battery, you
can either use `args.battery = "BAT*"` or `args.batteries = {"BAT*"}`, where `BAT*`
is the identifier of your battery in `pspath` (do not use it as a wildcard).
Of course, if you have multiple batteries, you need to use the latter option.
If you define `pspath`, **be sure** to not forget the final slash (/).
`settings` can use the `tpbat_now` table, which contains the following strings:
- `status`, general status ("N/A", "discharging", "charging", "full");
- `n_status[i]`, i-th battery status (like above);
- `n_perc[i]`, i-th battery charge percentage (like above);
- `n_time[i]`, i-th battery running or charging time (HH:MM string or "N/A");
`n_time[i]` is the running time of battery `i` when it is discharging, and the charging time otherwise.
### Output table
Variable | Meaning | Type
--- | --- | ---
`widget` | The widget | [`wibox.widget`](https://awesomewm.org/doc/api/classes/wibox.widget.html) | [textbox](https://awesomewm.org/doc/api/classes/wibox.widget.textbox.html)
`batteries` | Battery identifiers | Table of strings
`update` | Update `widget` | function
`timer` | The widget timer | [`gears.timer`](https://awesomewm.org/doc/api/classes/gears.timer.html)
The `update` function can be used to refresh the widget before `timeout` expires.
### Usage example
```lua
local tp_smapi = lain.widget.contrib.tp_smapi()
local bat = tp_smapi.create_widget {
battery = "BAT0",
settings = function()
widget:set_markup(tpbat_now.n_perc[1] .. "%")
end
}
bat.widget:connect_signal("mouse::enter", function () tp_smapi.show("BAT0") end)
bat.widget:connect_signal("mouse::leave", function () tp_smapi.hide() end)
```

222
awesome/lain/wiki/watch.md Normal file
View file

@ -0,0 +1,222 @@
## Usage
[Read here.](https://github.com/lcpz/lain/wiki/Widgets#usage)
### Description
Template for asynchronous watcher widgets.
Executes an input command and makes the user feed a `wibox.widget` with the output.
```lua
local mywatch = lain.widget.watch()
```
This has been implemented in Awesome 4.0 as [`awful.widget.watch`](https://awesomewm.org/doc/api/classes/awful.widget.watch.html). But while Awesome `watch` returns only the widget, Lain one returns a table including its timer and internal update function too.
## Input table
Variable | Meaning | Type | Default
--- | --- | --- | ---
`widget` | Widget to feed | `wibox.widget` | `wibox.widget.textbox`
`timeout` | Refresh timeout seconds | number | 5
`cmd` | The command to execute | string **or** table | `nil`
`nostart` | Widget timer doesn't start immediately | boolean | false
`stoppable` | Widget timer is stoppable | boolean | false
`settings` | User settings | function | see [Default `settings` function](https://github.com/lcpz/lain/wiki/watch#default-settings-function)
If your command needs a shell, you need to set `cmd` as an array of 3 strings, where the first contains the shell, the second contains `-c`, and the third contains the actual command. Example:
```lua
cmd = { awful.util.shell, "-c", "myactualcommand" }
```
`settings` can use the string `output`, which is the output of `cmd`.
### Default `settings` function
```lua
settings = function() widget:set_text(output) end
```
## Output table
Variable | Meaning | Type
--- | --- | ---
`widget` | The widget | input widget type or `wibox.widget.textbox`
`update` | Update `widget` | function
`timer` | The widget timer | [`gears.timer`](https://awesomewm.org/doc/api/classes/gears.timer.html) or `nil`
The `update` function can be used to refresh the widget before `timeout` expires.
If `stoppable == true`, the widget will have an ad-hoc timer, which you can control though `timer` variable.
## Use case examples
### bitcoin
```lua
-- Bitcoin to USD current price, using Coinbase V1 API
local bitcoin = lain.widget.watch({
timeout = 43200, -- half day
stoppable = true,
cmd = "curl -m5 -s 'https://coinbase.com/api/v1/prices/buy'",
settings = function()
local btc, pos, err = require("lain.util").dkjson.decode(output, 1, nil)
local btc_price = (not err and btc and btc["subtotal"]["amount"]) or "N/A"
-- customize here
widget:set_text(btc_price)
end
})
```
### btrfs
```lua
-- btrfs root df
local myrootfs = lain.widget.watch({
timeout = 600,
cmd = "btrfs filesystem df -g /",
settings = function()
local total, used = string.match(output, "Data.-total=(%d+%.%d+)GiB.-used=(%d+%.%d+)GiB")
local percent_used = math.ceil((tonumber(used) / tonumber(total)) * 100)
-- customize here
widget:set_text(" [/: " .. percent_used .. "%] ")
end
})
```
### cmus
```lua
-- cmus audio player
local cmus = lain.widget.watch({
timeout = 2,
stoppable = true,
cmd = "cmus-remote -Q",
settings = function()
local cmus_now = {
state = "N/A",
artist = "N/A",
title = "N/A",
album = "N/A"
}
for w in string.gmatch(output, "(.-)tag") do
a, b = w:match("(%w+) (.-)\n")
cmus_now[a] = b
end
-- customize here
widget:set_text(cmus_now.artist .. " - " .. cmus_now.title)
end
})
```
### maildir
```lua
-- checks whether there are files in the "new" directories of a mail dirtree
local mailpath = "~/Mail"
local mymaildir = lain.widget.watch({
timeout = 60,
stoppable = true,
cmd = { awful.util.shell, "-c", string.format("ls -1dr %s/*/new/*", mailpath) },
settings = function()
local inbox_now = { digest = "" }
for dir in output:gmatch(".-/(%w+)/new") do
inbox_now[dir] = 1
for _ in output:gmatch(dir) do
inbox_now[dir] = inbox_now[dir] + 1
end
if #inbox_now.digest > 0 then inbox_now.digest = inbox_now.digest .. ", " end
inbox_now.digest = inbox_now.digest .. string.format("%s (%d)", dir, inbox_now[dir])
end
-- customize here
widget:set_text("mail: " .. inbox_now.digest)
end
})
```
### mpris
```lua
-- infos from mpris clients such as spotify and VLC
-- based on https://github.com/acrisci/playerctl
local mpris = lain.widget.watch({
cmd = "playerctl status && playerctl metadata",
timeout = 2,
stoppable = true,
settings = function()
local escape_f = require("awful.util").escape
local mpris_now = {
state = "N/A",
artist = "N/A",
title = "N/A",
art_url = "N/A",
album = "N/A",
album_artist = "N/A"
}
mpris_now.state = string.match(output, "Playing") or
string.match(output, "Paused") or "N/A"
for k, v in string.gmatch(output, "'[^:]+:([^']+)':[%s]<%[?'([^']+)'%]?>")
do
if k == "artUrl" then mpris_now.art_url = v
elseif k == "artist" then mpris_now.artist = escape_f(v)
elseif k == "title" then mpris_now.title = escape_f(v)
elseif k == "album" then mpris_now.album = escape_f(v)
elseif k == "albumArtist" then mpris_now.album_artist = escape_f(v)
end
end
-- customize here
widget:set_text(mpris_now.artist .. " - " .. mpris_now.title)
end
})
```
### upower
```lua
-- battery infos from freedesktop upower
local mybattery = lain.widget.watch({
timeout = 30,
cmd = { awful.util.shell, "-c", "upower -i /org/freedesktop/UPower/devices/battery_BAT | sed -n '/present/,/icon-name/p'" },
settings = function()
local bat_now = {
present = "N/A",
state = "N/A",
warninglevel = "N/A",
energy = "N/A",
energyfull = "N/A",
energyrate = "N/A",
voltage = "N/A",
percentage = "N/A",
capacity = "N/A",
icon = "N/A"
}
for k, v in string.gmatch(output, '([%a]+[%a|-]+):%s*([%a|%d]+[,|%a|%d]-)') do
if k == "present" then bat_now.present = v
elseif k == "state" then bat_now.state = v
elseif k == "warning-level" then bat_now.warninglevel = v
elseif k == "energy" then bat_now.energy = string.gsub(v, ",", ".") -- Wh
elseif k == "energy-full" then bat_now.energyfull = string.gsub(v, ",", ".") -- Wh
elseif k == "energy-rate" then bat_now.energyrate = string.gsub(v, ",", ".") -- W
elseif k == "voltage" then bat_now.voltage = string.gsub(v, ",", ".") -- V
elseif k == "percentage" then bat_now.percentage = tonumber(v) -- %
elseif k == "capacity" then bat_now.capacity = string.gsub(v, ",", ".") -- %
elseif k == "icon-name" then bat_now.icon = v
end
end
-- customize here
widget:set_text("Bat: " .. bat_now.percentage .. " " .. bat_now.state)
end
})
```

150
awesome/lain/wiki/weather.md Normal file
View file

@ -0,0 +1,150 @@
## Usage
[Read here.](https://github.com/lcpz/lain/wiki/Widgets#usage)
### Description
Provides current weather status widgets and X-days forecast popup notifications.
Powered by [OpenWeatherMap](http://openweathermap.org/api) API.
By default, it uses [current](http://openweathermap.org/current) for current weather data and [forecast16](http://openweathermap.org/forecast16) for forecasts.
```lua
local myweather = lain.widget.weather()
```
## Input table
Variable | Meaning | Type | Default
--- | --- | --- | ---
`timeout` | Refresh timeout seconds for current weather status | number | 900 (15 min)
`timeout_forecast` | Refresh timeout seconds for forecast notification | number | 86400 (24 hrs)
`current_call` | Command to fetch weather status data from the API | string | see `default_current_call`
`forecast_call` | Command to fetch forecast data from the API | string | see `default_forecast_call`
`city_id` | API city code | number | not set
`utc_offset` | UTC time offset | function | see [here](https://github.com/lcpz/lain/blob/master/widget/weather.lua#L35-L39)
`units` | Temperature units system | string | "metric"
`lang` | API data localization | string | "en"
`cnt` | Forecast days interval | integer | 5
`date_cmd` | Forecast notification format style | string | "date -u -d @%d +'%%a %%d'"
`icons_path` | Icons path | string | `lain/icons/openweathermap`
`notification_preset` | Preset for notifications | table | empty table
`notification_text_fun` | Function to format forecast notifications | function | see `notification_text_fun` below
`weather_na_markup` | Markup to be used when weather textbox is not available | text | " N/A "
`followtag` | Display the notification on currently focused screen | boolean | false
`showpopup` | Display popups with mouse hovering | string, possible values: "on", "off" | "on"
`settings` | User settings | function | empty function
- ``default_current_call``
`"curl -s 'http://api.openweathermap.org/data/2.5/weather?id=%s&units=%s&lang=%s'"`
You can rewrite it using any fetcher solution you like, or you can modify it in order to fetch data by city name, instead of ID: just replace `id` with `q`:
`"curl -s 'http://api.openweathermap.org/data/2.5/weather?q=%s&units=%s&lang=%s'"`
and set `city_id` with your city name, for instance `city_id = "London,UK"`.
- ``default_forecast_call``
`"curl -s 'http://api.openweathermap.org/data/2.5/forecast/daily?id=%s&units=%s&lang=%s&cnt=%s'"`
Like above.
If you want to use [forecast5](http://openweathermap.org/forecast5), use this API call string:
`http://api.openweathermap.org/data/2.5/forecast?id=%s&units=%s&lang=%s&cnt=%s`
- ``city_id``
An integer that defines the OpenWeatherMap ID code of your city.
To obtain it go to [OpenWeatherMap](http://openweathermap.org/) and query for your city in the top search bar. The link will look like this:
http://openweathermap.org/city/2643743
your `city_id` is the number at the end.
- ``units``
- For temperature in Fahrenheit use `units = "imperial"`
- For temperature in Celsius use `units = "metric"` (Lain default)
- For temperature in Kelvin use `units = "standard"` (OpenWeatherMap default)
- ``lang``
See *Multilingual Support* section [here](http://openweathermap.org/current).
- ``cnt``
Determines how many days to show in the forecast notification. Up to 16 if you use [forecast16](http://openweathermap.org/forecast16) (default), and up to 5 if you use [forecast5](http://openweathermap.org/forecast5).
- ``date_cmd``
OpenWeatherMap time is in UNIX format, so this variable uses `date` to determine how each line in the forecast notification is formatted. Default looks like this:
day #daynumber: forecast, temp_min - temp_max
see `man date` for your customizations.
- ``icons_path``
You can set your own icons path if you don't wish to use `lain/icons/openweathermap`. Just be sure that your icons are PNGs and named exactly like [OpenWeatherMap ones](http://openweathermap.org/weather-conditions).
- ``notification_preset``
Notifications preset table. See [here](https://awesomewm.org/doc/api/libraries/naughty.html#notify) for the details.
- ``notification_text_fun``
```lua
function (wn)
local day = string.gsub(read_pipe(string.format(date_cmd, wn["dt"])), "\n", "")
local tmin = math.floor(wn["temp"]["min"])
local tmax = math.floor(wn["temp"]["max"])
local desc = wn["weather"][1]["description"]
return string.format("<b>%s</b>: %s, %d - %d ", day, desc, tmin, tmax)
end
```
See [here](https://github.com/lcpz/lain/issues/186#issuecomment-203400918) for a complete customization example.
- ``followtag``
With multiple screens, the default behaviour is to show a visual notification pop-up window on the first screen. By setting `followtag` to `true` it will be shown on the currently focused tag screen.
- ``settings``
In your `settings` function, you can use `widget` variable to refer to the textbox, and the dictionary `weather_now` to refer to data retrieved by `current_call`. The dictionary is built with [dkjson library](http://dkolf.de/src/dkjson-lua.fsl/home), and its structure is defined [here](http://openweathermap.org/weather-data).
For instance, you can retrieve current weather status and temperature in this way:
```lua
descr = weather_now["weather"][1]["description"]:lower()
units = math.floor(weather_now["main"]["temp"])
```
## Output table
Variable | Meaning | Type
--- | --- | ---
`widget` | The widget | `wibox.widget.textbox`
`icon` | The icon | `wibox.widget.imagebox`
`update` | Update `widget` | function
`timer` | The widget timer | [`gears.timer`](https://awesomewm.org/doc/api/classes/gears.timer.html)
`timer_forecast` | The forecast notification timer | [`gears.timer`](https://awesomewm.org/doc/api/classes/gears.timer.html)
## Functions
You can attach the forecast notification to any widget like this:
```lua
myweather.attach(obj)
```
Hovering over ``obj`` will display the notification.
## Keybindings
You can create a keybinding for the weather popup like this:
```lua
awful.key( { "Mod1" }, "w", function () myweather.show(5) end )
```
where ``show`` argument is an integer defining timeout seconds.