From: luke bonham Date: Tue, 21 Jan 2014 15:03:04 +0000 (+0100) Subject: wiki updated X-Git-Url: https://git.madduck.net/etc/awesome.git/commitdiff_plain/f87b80a92ce3a34c3f5843647be9c2189da53d99?ds=sidebyside;hp=-c wiki updated --- f87b80a92ce3a34c3f5843647be9c2189da53d99 diff --git a/Home.md b/Home.md deleted file mode 100644 index 5581a9e..0000000 --- a/Home.md +++ /dev/null @@ -1,34 +0,0 @@ -Welcome to the Lain wiki! - -Dependencies ------------------- - -Package | Requested by | Reason of choice ---- | --- | --- -alsa-utils | [alsa](https://github.com/copycat-killer/lain/wiki/alsa), [alsabar](https://github.com/copycat-killer/lain/wiki/alsabar) | / -curl | widgets accessing network resources | LuaSocket is not a core library, and still not available for Lua 5.2+. LuaSSL is out of date. -imagemagick | album arts in [mpd](https://github.com/copycat-killer/lain/wiki/mpd) notifications | Cairo doesn't do high quality filtering. - -Installation ---------------- - -### Arch Linux - -[AUR package](https://aur.archlinux.org/packages/lain/) - -### Other distributions - - git clone https://github.com/copycat-killer/lain.git ~/.config/awesome/lain - -Usage --------- - -First, include it into your `rc.lua`: - - local lain = require("lain") - -Then check out the submodules you want: - -- [Layouts](https://github.com/copycat-killer/lain/wiki/Layouts) -- [Widgets](https://github.com/copycat-killer/lain/wiki/Widgets) -- [Utilities](https://github.com/copycat-killer/lain/wiki/Utilities) \ No newline at end of file diff --git a/Layouts.md b/Layouts.md deleted file mode 100644 index 045c2c9..0000000 --- a/Layouts.md +++ /dev/null @@ -1,298 +0,0 @@ -Currently, there are **8** layouts. - - lain/layout - . - |-- termfair - |-- centerfair - |-- cascade - |-- cascadetile - |-- centerwork - |-- uselessfair - |-- uselesspiral - `-- uselesstile - -Just add your favourites to ``layouts`` table: - - layouts = - { - ... - lain.layout.termfair, - lain.layout.uselesstile, - ... - } - -Or set them on specific tags like this: - - awful.layout.set(lain.layout.uselessfair, tags[1][7]) - -How do layouts work? -========================= - -termfair --------- - -I do a lot of work on terminals. The common tiling algorithms usually -maximize windows, so you'll end up with a terminal that has about 200 -columns or more. That's way too much. Have you ever read a manpage in a -terminal of this size? - -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: - - lain.layout.termfair.nmaster = 3 - lain.layout.termfair.ncol = 1 - -centerfair ----------- - -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: - - lain.layout.centerfair.nmaster = 3 - lain.layout.centerfair.ncol = 1 - -cascade -------- - -Cascade all windows of a tag. - -You can control the offsets by setting these two variables: - - lain.layout.cascade.cascade_offset_x = 64 - lain.layout.cascade.cascade_offset_y = 16 - -The following reserves space for 5 windows: - - 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. - -cascadetile ------------ - -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: - - lain.layout.cascadetile.cascade_offset_x = 2 - lain.layout.cascadetile.cascade_offset_y = 32 - lain.layout.cascadetile.extra_padding = 5 - lain.layout.cascadetile.nmaster = 5 - lain.layout.ncol = 1 - -`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 `cascade_offset_x` to a very small value or even 0 is reccommended 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 in -the following four slots: - - +--------------------------+ - | +---+ +----------+ +---+ | - | | | | | | | | - | | 0 | | | | 1 | | - | | | | | | | | - | +---+ | MAIN | +---+ | - | +---+ | | +---+ | - | | | | | | | | - | | 2 | | | | 3 | | - | | | | | | | | - | +---+ +----------+ +---+ | - +--------------------------+ - -Yes, the number "four" is fixed. In total, you can only have five open -windows with this layout. Additional windows are not managed and set to -floating mode. **This is intentional**. - -You can set the order of the four auxiliary windows. This is the default -configuration: - - lain.layout.centerwork.top_left = 0 - lain.layout.centerwork.top_right = 1 - lain.layout.centerwork.bottom_left = 2 - lain.layout.centerwork.bottom_right = 3 - -This means: The bottom left slot will be occupied by the third window -(not counting the main window). Suppose you want your windows to appear -in this order: - - +--------------------------+ - | +---+ +----------+ +---+ | - | | | | | | | | - | | 3 | | | | 0 | | - | | | | | | | | - | +---+ | MAIN | +---+ | - | +---+ | | +---+ | - | | | | | | | | - | | 2 | | | | 1 | | - | | | | | | | | - | +---+ +----------+ +---+ | - +--------------------------+ - -This would require you to use these settings: - - lain.layout.centerwork.top_left = 3 - lain.layout.centerwork.top_right = 0 - lain.layout.centerwork.bottom_left = 2 - lain.layout.centerwork.bottom_right = 1 - -*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: - - 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), - ... - ) - -uselessfair, uselesspiral & uselesstile ---------------------------------------- -These are duplicates of the stock `fair`, `spiral` and `tile` layouts. - -However, "useless gaps" (see below) have been added. - -Useless gaps -============ - -Useless gaps are gaps between windows. They are "useless" because they -serve no special purpose despite increasing overview. I find it easier -to recognize window boundaries if windows are set apart a little bit. - -The `uselessfair` layout, for example, looks like this: - - +================+ - # # - # +---+ +---+ # - # | 1 | | | # - # +---+ | | # - # | 3 | # - # +---+ | | # - # | 2 | | | # - # +---+ +---+ # - # # - +================+ - -All of lain layouts provide useless gaps. To set the width of the gaps, -you have to add an item called `useless_gap_width` in your `theme.lua`. -If it doesn't exist, the width will default to 0. -Example: - - theme.useless_gap_width = 10 - -What about layout icons? -======================== - -They are located in ``lain/icons/layout``. - -To use them, add lines to your ``theme.lua`` like this: - - theme.lain_icons = os.getenv("HOME") .. "/.config/awesome/lain/icons/layout/default/" - theme.layout_termfair = theme.lain_icons .. "termfairw.png" - theme.layout_cascade = theme.lain_icons .. "cascadew.png" - theme.layout_cascadetile = theme.lain_icons .. "cascadetilew.png" - theme.layout_centerwork = theme.lain_icons .. "centerworkw.png" - -Credits 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. - -[<- home](https://github.com/copycat-killer/lain/wiki) \ No newline at end of file diff --git a/Utilities.md b/Utilities.md deleted file mode 100644 index 99588b9..0000000 --- a/Utilities.md +++ /dev/null @@ -1,163 +0,0 @@ -markup ------- - -Made markup easier! - -First, require it like this: - - local markup = lain.util.markup - -then you can call its 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. - | - |`--+ bg - | | - | |`-- color() Set background color. - | |`-- focus() Set focus background color. - | |`-- normal() Set normal background color. - | `-- urgent() Set urgent background color. - | - |`--+ fg - | | - | |`-- color() Set foreground color. - | |`-- focus() Set focus foreground color. - | |`-- normal() Set normal foreground color. - | `-- urgent() Set urgent foreground color. - | - |`-- focus() Set both foreground and background focus colors. - |`-- normal() Set both foreground and background normal colors. - `-- urgent() Set both foreground and background urgent colors. - -they all take one argument, which is the text to markup, except `fg.color` and `bg.color`: - - markup.fg.color(text, color) - markup.bg.color(text, color) - -dynamic tagging ---------------- - -That is: - -- add a new tag; -- rename current tag; -- move current tag; -- remove 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: - - awful.key({ modkey, "Shift" }, "n", function () lain.util.add_tag(mypromptbox) end), - awful.key({ modkey, "Shift" }, "r", function () lain.util.rename_tag(mypromptbox) 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.remove_tag() end), - -**Note** that these function won't work properly with [Copland theme](https://github.com/copycat-killer/awesome-copycats) or any other configuration that already uses a dynamic tagging module like [Eminent](https://github.com/copycat-killer/awesome-copycats/tree/master/eminent). - -useless\_gaps\_resize ---------------------- - -Changes `beautiful.useless_gaps_width` on the fly. - -The function takes an integer argument, being the amount of pixel to add/remove to gaps. - -You could use it with these keybindings: - - -- 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`, or you could use it like this: - - 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: - - -- 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"`. - -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: - - awful.key({ "Mod1" }, "Tab", - function() - awful.menu.menu_keys.down = { "Down", "Alt_L", "Tab", "j" } - awful.menu.menu_keys.up = { "Up", "k" } - lain.util.menu_clients_current_tags({ width = 350 }, { keygrabber = true }) - end), - -magnify\_client ---------------- - -Set a client to floating and resize it in the same way the "magnifier" -layout does it. Place it on the "current" screen (derived from the mouse -position). This allows you to magnify any client you wish, regardless of -the currently used layout. Use it with a client keybinding like this: - - clientkeys = awful.util.table.join( - ... - awful.key({ modkey, "Control" }, "m", lain.util.magnify_client), - ... - ) - -If you want to "de-magnify" it, just retype the keybinding. - -niceborder\_{focus, unfocus} ----------------------------- - -By default, your `rc.lua` contains something like this: - - client.connect_signal("focus", function(c) c.border_color = beautiful.border_focus end) - client.connect_signal("unfocus", function(c) c.border_color = beautiful.border_normal end) - -You can change it to this: - - client.connect_signal("focus", lain.util.niceborder_focus(c)) - client.connect_signal("unfocus", lain.util.niceborder_unfocus(c)) - -Now, when a client is focused or unfocused, Awesome will look up its -nice value in `/proc//stat`. If it's less than 0, the client is -classified as "high priority"; if it's greater than 0, the client is -classified as "low priority". If it's equal to 0, nothing special -happens. - -This requires to define additional colors in your `theme.lua`. For example: - - theme.border_focus_highprio = "#FF0000" - theme.border_normal_highprio = "#A03333" - - theme.border_focus_lowprio = "#3333FF" - theme.border_normal_lowprio = "#333366" \ No newline at end of file diff --git a/Widgets.md b/Widgets.md deleted file mode 100644 index 5917aac..0000000 --- a/Widgets.md +++ /dev/null @@ -1,53 +0,0 @@ -General usage -------------- - -Every widget is output by a `function`. - -For some widgets, `function` returns a `wibox.widget.textbox`, for others a table to be used for notification and update purposes. - -Every widget may take either a table or a list of variables as argument. - -If it takes a table, you have to define a function variable called `settings` in it, in order to make your customizations. - -To markup the textbox, call `widget:set_markup(...)` within `settings`. - -You can feed `set_markup` with predefined arguments, see the sections for all the details. - -`widget` is a textbox, so you can threat it like any other `wibox.widget.textbox`. - -Here follows an example: - - mycpu = lain.widgets.cpu({ - timeout = 4, - settings = function() - widget:set_markup("Cpu " .. cpu_now.usage) - end - }) - -If you want to see more complex applications, check [awesome-copycats](https://github.com/copycat-killer/awesome-copycats). - -Index ------ - -- [alsa](https://github.com/copycat-killer/lain/wiki/alsa) -- [alsabar](https://github.com/copycat-killer/lain/wiki/alsabar) -- [bat](https://github.com/copycat-killer/lain/wiki/bat) -- [borderbox](https://github.com/copycat-killer/lain/wiki/borderbox) -- [calendar](https://github.com/copycat-killer/lain/wiki/calendar) -- [cpu](https://github.com/copycat-killer/lain/wiki/cpu) -- [fs](https://github.com/copycat-killer/lain/wiki/fs) -- [imap](https://github.com/copycat-killer/lain/wiki/imap) -- [maildir](https://github.com/copycat-killer/lain/wiki/maildir) -- [mem](https://github.com/copycat-killer/lain/wiki/mem) -- [mpd](https://github.com/copycat-killer/lain/wiki/mpd) -- [net](https://github.com/copycat-killer/lain/wiki/net) -- [sysload](https://github.com/copycat-killer/lain/wiki/sysload) -- [temp](https://github.com/copycat-killer/lain/wiki/temp) -- [yawn](https://github.com/copycat-killer/lain/wiki/yawn) - -Users contributed ----------------- - -- [task](https://github.com/copycat-killer/lain/wiki/task) -- [tpbat](https://github.com/copycat-killer/lain/wiki/tpbat) -- [brightness](https://github.com/copycat-killer/lain/wiki/brightness) \ No newline at end of file diff --git a/alsa.md b/alsa.md deleted file mode 100644 index daf4016..0000000 --- a/alsa.md +++ /dev/null @@ -1,53 +0,0 @@ -[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets) - -Shows and controls alsa volume with a textbox. - - volumewidget = lain.widgets.alsa() - -### input table - -Variable | Meaning | Type | Default ---- | --- | --- | --- -`timeout` | Refresh timeout seconds | int | 5 -`channel` | Mixer channel | string | "Master" -`settings` | User settings | function | empty function - -`settings` can use the following variables: - -Variable | Meaning | Type | Values ---- | --- | --- | --- -`volume_now.level` | Self explained | int | 0-100 -`volume_now.status` | Device status | string | "on", "off" - -### output table - -Variable | Meaning | Type ---- | --- | --- -`widget` | The widget | `wibox.widget.textbox` -`update` | Update `widget` | function - -You can control the widget with key bindings like these: - - -- Volume control - awful.key({ altkey }, "Up", - function () - awful.util.spawn("amixer set Master 1%+") - volumewidget.update() - end), - awful.key({ altkey }, "Down", - function () - awful.util.spawn("amixer set Master 1%-") - volumewidget.update() - end), - awful.key({ altkey }, "m", - function () - awful.util.spawn("amixer set Master playback toggle") - volumewidget.update() - end), - awful.key({ altkey, "Control" }, "m", - function () - awful.util.spawn("amixer set Master playback 100%", false ) - volumewidget.update() - end), - -where `altkey = "Mod1"`. \ No newline at end of file diff --git a/alsabar.md b/alsabar.md deleted file mode 100644 index 6138f2c..0000000 --- a/alsabar.md +++ /dev/null @@ -1,85 +0,0 @@ -[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets) - -Shows and controls alsa volume with a progressbar; provides tooltips, notifications, and color changes at mute/unmute switch. - - volume = lain.widgets.alsabar() - -* Left click: Launch `alsamixer` in your `terminal`. -* Right click: Mute/unmute. -* Scroll wheel: Increase/decrase volume. - -The function takes a table as optional argument, which can contain: - -Variable | Meaning | Type | Default ---- | --- | --- | --- -`timeout` | Refresh timeout seconds | int | 4 -`settings` | User settings | function | empty function -`width` | Bar width | int | 63 -`height` | Bar height | int | 1 -`ticks` | Set bar ticks on | boolean | false -`ticks_size` | Ticks size | int | 7 -`vertical` | Set the bar vertical | boolean | false -`channel` | Mixer channel | string | "Master" -`step` | Step at which volume is increased/decreased | string | "5%" -`colors` | Bar colors | table | see **colors** -`notifications` | Notifications settings | table | see **notifications** - -### colors - -Variable | Meaning | Type | Default ---- | --- | --- | --- -`background` | Bar backgrund color | string | `beautiful.bg_normal` -`mute` | Bar mute color | string | "#EB8F8F" -`unmute` | Bar unmute color | string | "#A4CE8A" - -### notifications - -Variable | Meaning | Type | Default ---- | --- | --- | --- -`font` | Notifications font | string | The one defined in `beautiful.font` -`font_size` | Notifications font size | string | "11" -`color` | Notifications color | string | `beautiful.fg_normal` -`bar_size` | Wibox height | int | 18 - -It's **crucial** to set `notifications.bar_size` to your `mywibox[s]` height. - -`settings` can use the following variables: - -Variable | Meaning | Type | Values ---- | --- | --- | --- -`volume_now.level` | Self explained | int | 0-100 -`volume_now.status` | Device status | string | "on", "off" -### output table - -Variable | Meaning | Type ---- | --- | --- -`bar` | The widget | `awful.widget.progressbar` -`channel` | Alsa channel | string -`step` | Increase/decrease step | string -`notify` | The notification | function - -You can control the widget with key bindings like these: - - -- ALSA volume control - awful.key({ altkey }, "Up", - function () - awful.util.spawn("amixer -q set " .. volume.channel .. " " .. volume.step .. "+") - volume.notify() - end), - awful.key({ altkey }, "Down", - function () - awful.util.spawn("amixer -q set " .. volume.channel .. " " .. volume.step .. "-") - volume.notify() - end), - awful.key({ altkey }, "m", - function () - awful.util.spawn("amixer -q set " .. volume.channel .. " playback toggle") - volume.notify() - end), - awful.key({ altkey, "Control" }, "m", - function () - awful.util.spawn("amixer -q set " .. volume.channel .. " playback 100%") - volume.notify() - end), - -where `altkey = "Mod1"`. \ No newline at end of file diff --git a/bat.md b/bat.md deleted file mode 100644 index 6bbb21e..0000000 --- a/bat.md +++ /dev/null @@ -1,30 +0,0 @@ -[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets) - -Shows in a textbox the remaining time and percentage capacity of your laptop battery, as well as -the current wattage. - -Displays a notification when battery is low or critical. - - mybattery = lain.widgets.bat() - -### input table - -Variable | Meaning | Type | Default ---- | --- | --- | --- -`timeout` | Refresh timeout seconds | int | 30 -`battery` | Identifier of the battery | string | "BAT0" -`notify` | Enable notifications | string | "on" -`settings` | User settings | function | empty function - -`settings` can use the `bat_now` table, which contains the following strings: - -- `status` ("Not present", "Charging", "Discharging"); -- `perc`; -- `time`; -- `watt`. - -To disable warning notifications, set `notify` to `"off"`. - -### output - -A textbox. \ No newline at end of file diff --git a/borderbox.md b/borderbox.md deleted file mode 100644 index a56026a..0000000 --- a/borderbox.md +++ /dev/null @@ -1,49 +0,0 @@ -[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets) - -Creates a thin wibox at a position relative to another wibox. - -This allows to create "borders" for your wiboxes. - - lain.widget.borderbox(relbox, s, args) - -`relbox` and `s` (an integer being screen number) are required arguments, `args` is an optional table -which can contain: - -Variable | Meaning | Type | Default ---- | --- | --- | --- -`position` | Position of the additional box | string | "above" -`color` | Color of the additional box | string | `#FFFFFF` -`size` | Size in pixels of the additional box | int | 1 - -Possible values for `.position`: `top`, `bottom`, `left` and `right`. - -### Example usage - -Think of this as a wibox: - - [======================] - -If `args.position = "above"`, then you'll get an additional wibox below -the existing one: - - ________________________ - [======================] - -It'll match position and size of the existing wibox. - -If your main wiboxes are stored in a table called `mywibox` (one wibox -for each screen) and are located at the bottom of your screen, then this -adds a borderbox on top of them: - - -- Layout section - for s = 1, screen.count() do - ... - - -- Most likely, you'll want to do this as well: - awful.screen.padding(screen[s], "bottom") - - -- Create the box and place it above the existing box. - lain.widgets.borderbox(mywibox[s], s ) - - ... - end \ No newline at end of file diff --git a/brightness.md b/brightness.md deleted file mode 100644 index 4cd4f8e..0000000 --- a/brightness.md +++ /dev/null @@ -1,40 +0,0 @@ -[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets) - -Shows the current level of screen brightness in a textbox. - - brightnesswidget = lain.widgets.contrib.brightness() - -### input table - -Variable | Meaning | Type | Default ---- | --- | --- | --- -`timeout` | Refresh timeout seconds | int | 5 -`backlight` | Backlight video | string | "acpi_video0" -`settings` | User settings | function | empty function - -`settings` can use the following variables: - -Variable | Meaning | Type | Values ---- | --- | --- | --- -`brightness_now` | Brightness level | int | 0-100 - -### output table - -Variable | Meaning | Type ---- | --- | --- -`widget` | The widget | `wibox.widget.textbox` -`update` | Update `widget` | function - -You can control the widget with key bindings like these: - - -- Brightness control - awful.key({}, "XF86MonBrightnessUp", - function () - awful.util.spawn("xbacklight -inc 1") - brightnesswidget.update() - end), - awful.key({}, "XF86MonBrightnessDown", - function () - awful.util.spawn("xbacklight -dec 1") - brightnesswidget.update() - end), \ No newline at end of file diff --git a/calendar.md b/calendar.md deleted file mode 100644 index b06c453..0000000 --- a/calendar.md +++ /dev/null @@ -1,31 +0,0 @@ -[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets) - -Attaches a calendar notification to a widget. - - lain.widgets.calendar:attach(widget, args) - -- Left click: switch to previous month. -- Right click: switch to next month. - -`args` is an optional table which can contain: - -Variable | Meaning | Type | Default ---- | --- | --- | --- -`icons` | Path to calendar icons | string | [lain/icons/cal/white](https://github.com/copycat-killer/lain/tree/master/icons/cal/white) -`font_size` | Calendar font size | int | 12 -`fg` | Calendar foreground color | string | `beautiful.fg_normal` -`bg` | Calendar background color | string | `beautiful.bg_normal` -`position` | Calendar position | string | "top_right" - -`position` possible values are defined [here](http://awesome.naquadah.org/doc/api/modules/naughty.html#notify). - -Notification will show an icon displaying current day, and formatted output -from ``cal`` with current day highlighted. - -You can call the notification with a key binding like this: - - awful.key({ altkey }, "c", function () lain.widgets.calendar:show(7) end), - -where ``altkey = "Mod1"`` and ``show`` argument is an optional integer, meaning timeout seconds. - -**Note that** this widget exploits ``cal`` to do the alignment, in order to avoid more dozens of code lines, but this requires that your system font is monospaced. \ No newline at end of file diff --git a/cpu.md b/cpu.md deleted file mode 100644 index e42180c..0000000 --- a/cpu.md +++ /dev/null @@ -1,18 +0,0 @@ -[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets) - -Shows in a textbox the average CPU usage percent for a given amount of time. - - mycpuusage = lain.widgets.cpu() - -### input table - -Variable | Meaning | Type | Default ---- | --- | --- | --- -`timeout` | Refresh timeout seconds | int | 5 -`settings` | User settings | function | empty function - -`settings` can use the string `cpu_now.usage`, which is the cpu use percentage. - -### output - -A textbox. \ No newline at end of file diff --git a/fs.md b/fs.md deleted file mode 100644 index 1e34f86..0000000 --- a/fs.md +++ /dev/null @@ -1,45 +0,0 @@ -[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets) - -Shows disk space usage for a set partition. - -Displays a notification when the partition is full or has low space. - - mypartition = lain.widgets.fs() - -### input table - -Variable | Meaning | Type | Default ---- | --- | --- | --- -`timeout` | Refresh timeout seconds -| int | 600 -`partition` | Partition to monitor | string | "/" -`settings` | User settings | function | empty function - -`settings` can use the following `partition` related float values: `fs_now.used`, `fs_now.available`, `fs_now.size_mb`, `fs_now.size_gb`. - -It can also use value strings in these formats: - - fs_info[p .. "used_p"] - fs_info[p .. "avail_p"] - fs_info[p .. "size_mb"] - fs_info[p .. "size_gb"] - -where `p` is the last column of `df` command ("/", "/home", "/boot", ...). - -This means you can set the widget for a certain partition, but you can look up at others too. - -Finally, `settings` can modify `fs_notification_preset` table too. This table will be the preset for the naughty notifications. Check [here](http://awesome.naquadah.org/doc/api/modules/naughty.html#notify) for the list of variables it can contain. Default definition: - - fs_notification_preset = { fg = beautiful.fg_normal } - -### 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: - - awful.key({ altkey }, "h", function () mypartition.show(7) end), - -where ``altkey = "Mod1"`` and ``show`` argument is an optional integer, meaning timeout seconds. \ No newline at end of file diff --git a/imap.md b/imap.md deleted file mode 100644 index 403a61a..0000000 --- a/imap.md +++ /dev/null @@ -1,68 +0,0 @@ -[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets) - -Shows mail count in a textbox fetching over IMAP. - - myimapcheck = lain.widgets.imap(args) - -New mails are notified like this: - - +--------------------------------------------+ - | +---+ | - | |\ /| donald@disney.org has 3 new messages | - | +---+ | - +--------------------------------------------+ - -The function takes a table as argument. Required table 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 | int | 993 -`timeout` | Refresh timeout seconds | int | 60 -`is_plain` | Define whether `password` is a plain password (true) or a function that retrieves it (false) | boolean | false -`settings` | User settings | function - -Let's focus better on `is_plain`. - -The reason why it's false by default is to discourage the habit of storing passwords in plain. - -So you can set your password in plain like this: - - myimapcheck = lain.widgets.imap({ - is_plain = true, - password = "myplainpassword", - [...] - }) - -and you'll have the same security provided by `~/.netrc`. - -**Or** you can use a keyring, like [python keyring](https://pypi.python.org/pypi/keyring): - - myimapcheck = lain.widgets.imap({ - password = "keyring get mymail", - [...] - }) - -When `is_plain == false`, it *executes* `password` before using it, so you can also use whatever password fetching solution you want. - -`settings` can use the value `mailcount`, an integer greater or equal to zero, and can modify `mail_notification_preset` table, which will be the preset for the naughty notifications. Check [here](http://awesome.naquadah.org/doc/api/modules/naughty.html#notify) for the list of variables it can contain. - -Default definition: - - mail_notification _preset = { - icon = lain/icons/mail.png, - position = "top_left" - } - -Note that `mailcount` is 0 either if there are no new mails or credentials are invalid, so make sure you get the right settings. - -### output - -A textbox. \ No newline at end of file diff --git a/maildir.md b/maildir.md deleted file mode 100644 index 355ecdd..0000000 --- a/maildir.md +++ /dev/null @@ -1,39 +0,0 @@ -[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets) - -Shows maildirs status in a textbox. - -Maildirs are structured as follows: - - ~/Mail - . - |-- arch - | |-- cur - | |-- new - | `-- tmp - |-- gmail - | |-- cur - | |-- new - | `-- tmp - . - . - . - -therefore the widget checks whether there are files in the `new` directories. -If there's new mails, the textbox will say something like "mail: bugs(3), system(1)", otherwise it says -"no mail". - - mymaildir = lain.widgets.maildir("/path/to/my/maildir") - -### input table - -Variable | Meaning | Type | Default ---- | --- | --- | --- -`timeout` | Refresh timeout seconds | int | 60 -`mailpath` | Path to your maildir | string | "~/Mail" -`settings` | User settings | function | empty function - -`settings` can use the string `newmail`, which format will be something like defined above, or "no mail". - -### output - -A textbox. \ No newline at end of file diff --git a/mem.md b/mem.md deleted file mode 100644 index 84b7ad2..0000000 --- a/mem.md +++ /dev/null @@ -1,18 +0,0 @@ -[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets) - -Shows memory status (in MiB) in a textbox. - - mymem = lain.widgets.mem() - -### input table - -Variable | Meaning | Type | Default ---- | --- | --- | --- -`timeout` | Refresh timeout seconds | int | 3 -`settings` | User settings | function | empty function - -`settings` can use the strings `mem_now.used` (memory used MB) and `mem_now.swapused` (swap used MB). - -### output - -A textbox. \ No newline at end of file diff --git a/mpd.md b/mpd.md deleted file mode 100644 index 646b690..0000000 --- a/mpd.md +++ /dev/null @@ -1,85 +0,0 @@ -[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets) - -Shows MPD status in a textbox. - - mpdwidget = lain.widgets.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) | - | +-------+ | - +--------------------------------------------------------+ - -You need a file like this - - (Front|front|Cover|cover|Art|art|Folder|folder)\.(jpg|jpeg|png|gif) - -in the album folder in order to show album art too. - -### input table - -Variable | Meaning | Type | Default ---- | --- | --- | --- -`timeout` | Refresh timeout seconds | int | 1 -`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 | int | 100 -`default_art` | Default art | string | "" -`settings` | User settings | function | empty function - -`settings` can use `mpd_now` table, which contains the following string values: - -- state (possible values: "play", "pause", "stop") -- file -- artist -- title -- album -- date - -and can modify `mpd_notification_preset` table, which will be the preset for the naughty notifications. Check [here](http://awesome.naquadah.org/doc/api/modules/naughty.html#notify) for the list of variables it can contain. Default definition: - - 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) - } - -### output table - -Variable | Meaning | Type ---- | --- | --- -`widget` | The textbox | `wibox.widget.textbox` -`update` | The notification | function - -You can control the widget with key bindings like these: - - -- MPD control - awful.key({ altkey, "Control" }, "Up", - function () - awful.util.spawn_with_shell("mpc toggle || ncmpcpp toggle || ncmpc toggle || pms toggle") - mpdwidget.update() - end), - awful.key({ altkey, "Control" }, "Down", - function () - awful.util.spawn_with_shell("mpc stop || ncmpcpp stop || ncmpc stop || pms stop") - mpdwidget.update() - end), - awful.key({ altkey, "Control" }, "Left", - function () - awful.util.spawn_with_shell("mpc prev || ncmpcpp prev || ncmpc prev || pms prev") - mpdwidget.update() - end), - awful.key({ altkey, "Control" }, "Right", - function () - awful.util.spawn_with_shell("mpc next || ncmpcpp next || ncmpc next || pms next") - mpdwidget.update() - end), - -where `altkey = "Mod1"`. \ No newline at end of file diff --git a/net.md b/net.md deleted file mode 100644 index f857239..0000000 --- a/net.md +++ /dev/null @@ -1,26 +0,0 @@ -[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets) - -Monitors network interfaces and shows current traffic in a textbox. - - mynet = lain.widgets.net() - -### input table - -Variable | Meaning | Type | Default ---- | --- | --- | --- -`timeout` | Refresh timeout seconds | int | 2 -`iface` | Network device | string | autodetected -`units` | Units | int | 1024 (kilobytes) -`settings` | User settings | function | empty function - -Possible other values for `units` are 1 (byte) or multiple of 1024: 1024^2 (mb), 1024^3 (gb), and so on. - -`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). - -### output - -A textbox. \ No newline at end of file diff --git a/sysload.md b/sysload.md deleted file mode 100644 index 3e53881..0000000 --- a/sysload.md +++ /dev/null @@ -1,18 +0,0 @@ -[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets) - -Shows the current system load. - - mysysload = lain.widgets.sysload() - -### input table - -Variable | Meaning | Type | Default ---- | --- | --- | --- -`timeout` | Refresh timeout seconds | int | 5 -`settings` | User settings | function | empty function - -`settings` can use strings `load_1`, `load_5` and `load_15`, which are loadavg over 1, 5, and 15 minutes. - -### output - -A textbox. \ No newline at end of file diff --git a/task.md b/task.md deleted file mode 100644 index b4bc7f0..0000000 --- a/task.md +++ /dev/null @@ -1,30 +0,0 @@ -[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets) - -Attaches a [taskwarrior](http://taskwarrior.org/projects/show/taskwarrior) notification to a widget, and lets to add/search tasks from the promptbox. - - lain.widgets.contrib.task:attach(widget, args) - -`args` is an optional table which can contain: - -Variable | Meaning | Type | Default ---- | --- | --- | --- -`font_size` | Calendar font size | int | 12 -`fg` | Calendar foreground color | string | `beautiful.fg_normal` -`bg` | Calendar background color | string | `beautiful.bg_normal` -`position` | Calendar position | string | "top_right" -`timeout` | Notification timeout seconds | int | 7 - -`position` possible values are defined [here](http://awesome.naquadah.org/doc/api/modules/naughty.html#notify). - -Notification will show the output of `task` command. - -You can call the notification with a key binding like this: - - awful.key({ modkey, altkey }, "t", lain.widgets.contrib.task.show), - -where ``altkey = "Mod1"``. - -And you can prompt to add/search a task with key bindings like these: - - awful.key({ modkey, }, "t", lain.widgets.contrib.task.prompt_add), - awful.key({ modkey, "Shift" }, "t", lain.widgets.contrib.task.prompt_search), \ No newline at end of file diff --git a/temp.md b/temp.md deleted file mode 100644 index 91f3031..0000000 --- a/temp.md +++ /dev/null @@ -1,20 +0,0 @@ -[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets) - -Shows the current core temperature in a textbox. - -Reads from `/sys/class/thermal`, so value is expressed in Celsius. - - mytemp = lain.widgets.temp() - -### input table - -Variable | Meaning | Type | Default ---- | --- | --- | --- -`timeout` | Refresh timeout seconds | int | 5 -`settings` | User settings | function | empty function - -`settings` can use the string `coretemp_now`, which means current core temperature, expressed in Celsius (linux standard). - -### output - -A textbox. \ No newline at end of file diff --git a/tpbat.md b/tpbat.md deleted file mode 100644 index 5a7ba0c..0000000 --- a/tpbat.md +++ /dev/null @@ -1,9 +0,0 @@ -[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets) - -A battery widget that works with Lenovo ThinkPad laptops using [tp_smapi](http://www.thinkwiki.org/wiki/Tp_smapi). - -Includes hover notification with more details. - - tpbatwidget = lain.widgets.contrib.tpbat() - -Configuration is identical to [standard battery widget's](https://github.com/copycat-killer/lain/wiki/bat). \ No newline at end of file diff --git a/wiki b/wiki index f996cdb..2fe55cb 160000 --- a/wiki +++ b/wiki @@ -1 +1 @@ -Subproject commit f996cdb74e7583534256d82706ef63d2b9811b42 +Subproject commit 2fe55cb50b4192866551d50dce563a52234961c7 diff --git a/yawn.md b/yawn.md deleted file mode 100644 index 30d160c..0000000 --- a/yawn.md +++ /dev/null @@ -1,93 +0,0 @@ -[<- widgets](https://github.com/copycat-killer/lain/wiki/Widgets) - -(YAhoo! Weather Notification) - -Yawn provides brief and compact Yahoo! Weather notification. - -Usage ------ - -You can ``register`` Yawn to get a set of widgets, or ``attach`` it to -an existent widget. - -### register - - yawn = lain.widgets.yawn(id, args) - -- ``id`` - - An integer that defines the WOEID code of your city. - To obtain it you can google 'yahoo weather %CITYNAME%' and follow the first link. - It will look like: - - http://weather.yahoo.com/united-states/california/san-diego-2487889/ - - and the last number in that link will be the ID you need. - -- ``args`` - - A required table which can contain: - - Variables | Meaning | Type | Possible values | Default value - --- | --- | --- | --- | --- - `u` | Units | string | "c" (Celsius), "f" (Fahrenheit) | "c" - `timeout` | Refresh timeout seconds | int | integers | 600 - `settings` | User settings | function | function | empty function - - `settings` can use strings `forecast`, `units`, and can modify `yawn_notification_preset` table, which - will be the preset for the naughty notifications. Check [here](http://awesome.naquadah.org/doc/api/modules/naughty.html#notify) for the list of variables it can contain. - -The function `register` creates an imagebox icon and a textbox widget. Add them to you wibox like this: - - right_layout:add(yawn.icon) - right_layout:add(yawn.widget) - -Hovering over ``yawn.icon`` will display the notification. - -### attach - - lain.widgets.yawn.attach(widget, id, args) - -Arguments: - -- ``widget`` - - The widget which you want to attach Yawn to. - -- ``id`` - - Same as in ``register``. - -- ``args`` - - Same as in ``register``. - -Hovering over ``widget`` will display the notification. - -Popup shortcut --------------- - -You can also create a keybinding for the weather popup like this: - - awful.key( { "Mod1" }, "w", function () yawn.show(5) end ) - -where ``show`` argument is an integer defining timeout seconds. - -Localization ------------- - -Default language is English, but Yawn can be localized. - -Move to `localizations` subdirectory and fill `localization_template`. - -Once you're done, rename it like your locale id. In my case: - - $ lua - Lua 5.2.2 Copyright (C) 1994-2013 Lua.org, PUC-Rio - > print(os.getenv("LANG"):match("(%S*$*)[.]")) - it_IT - > - -hence I named my file "it_IT" (Italian localization). - -**NOTE:** If you create a localization, feel free to send me! I will add it. \ No newline at end of file