Lain

https://github.com/lcpz/lain
Admin
missing description
Tokens:23,625
Snippets:278
Trust Score:8
License:GPL-2.0
Update:4 months ago
Show doc for...
Tokens:
Raw
### PulseAudio Widget Example

Source: https://github.com/lcpz/lain/wiki/pulse

Full example of initializing the widget with custom settings for display.

```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
}
```

--------------------------------

### Initialize a CPU widget

Source: https://github.com/lcpz/lain/wiki/Widgets

Example of creating a CPU widget with a custom settings function to update the widget markup.

```lua
local cpu = lain.widget.cpu {
    settings = function()
        widget:set_markup("Cpu " .. cpu_now.usage)
    end
}
-- to access the widget: cpu.widget
```

--------------------------------

### Install Lain via Git

Source: https://github.com/lcpz/lain/wiki/Home

Clone the repository directly into the AwesomeWM configuration directory.

```shell
git clone https://github.com/lcpz/lain.git ~/.config/awesome/lain
```

--------------------------------

### Configure and use tp_smapi widget

Source: https://github.com/lcpz/lain/wiki/tp_smapi

Example showing widget creation with custom settings and signal connections for notifications.

```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)
```

--------------------------------

### Clone and Install Lain Locally

Source: https://github.com/lcpz/lain/wiki/widget_contrib_guide

Commands to clone the repository and install the library to the local user Luarocks directory.

```bash
git clone git@github.com:<yourusername>/lain
cd lain
luarocks make --local --force
```

--------------------------------

### Configure widget settings

Source: https://github.com/lcpz/lain/wiki/fs

Example of using the settings function to display specific file system metrics like percentage and free space.

```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)"
```

--------------------------------

### Install Lain via LuaRocks

Source: https://github.com/lcpz/lain/wiki/Home

Install the package using the LuaRocks package manager.

```shell
luarocks install lain
```

--------------------------------

### Key bindings for gap resizing

Source: https://github.com/lcpz/lain/wiki/Utilities

Examples for changing client gaps using keyboard shortcuts or mouse wheel events.

```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),
```

```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)
))
```

--------------------------------

### Configure AwesomeWM Package Path

Source: https://github.com/lcpz/lain/wiki/widget_contrib_guide

Add this to the top of rc.lua to ensure AwesomeWM can locate the locally installed Lain library.

```lua
-- we assume that your Lua is version 5.4
package.path = package.path .. ';/home/<your-account>/.luarocks/share/lua/5.4/?/init.lua'
local lain = require("lain")
```

--------------------------------

### Define default notification preset

Source: https://github.com/lcpz/lain/wiki/alsabar

Example configuration for the notification_preset table.

```lua
notification_preset = {
    font = "Monospace 10"
}
```

--------------------------------

### Split Upload and Download Widgets

Source: https://github.com/lcpz/lain/wiki/net

Example of using two separate widgets to display upload and download rates from the same interface.

```lua
local mynetdown = wibox.widget.textbox()
local mynetup = lain.widget.net {
    settings = function()
        widget:set_markup(net_now.sent)
        mynetdown:set_markup(net_now.received)
    end
}
```

--------------------------------

### Rebuild Widget for Testing

Source: https://github.com/lcpz/lain/wiki/widget_contrib_guide

Run this command after every code change to update the installed library before reloading AwesomeWM.

```bash
luarocks make --local --force
```

--------------------------------

### Bind notification display to a key

Source: https://github.com/lcpz/lain/wiki/fs

Example of triggering the partition notification via a keyboard shortcut.

```lua
awful.key({ altkey }, "h", function () mypartition.show(seconds, scr) end),
```

--------------------------------

### Bind Calendar to Key

Source: https://github.com/lcpz/lain/wiki/cal

Example keybinding to trigger the calendar display for a specific duration.

```lua
awful.key({ altkey }, "c", function () mycal.show(7) end)
```

--------------------------------

### Access Weather Data in Settings

Source: https://github.com/lcpz/lain/wiki/weather

Example of accessing current weather data within the settings function.

```lua
descr = weather_now["weather"][1]["description"]:lower()
units = math.floor(weather_now["main"]["temp"])
```

--------------------------------

### Verify Luarocks Installation

Source: https://github.com/lcpz/lain/wiki/widget_contrib_guide

Command to list installed Luarocks packages to ensure only one version of Lain is present.

```bash
luarocks list
```

--------------------------------

### lain.widget.sysload()

Source: https://github.com/lcpz/lain/wiki/sysload

Initializes the system load widget.

```APIDOC
## lain.widget.sysload()

### Description
Initializes a widget to display the current system load averages.

### Input Parameters
- **timeout** (integer) - Optional - Refresh timeout in seconds (default: 2).
- **settings** (function) - Optional - User settings function. Can access `load_1`, `load_5`, and `load_15` variables.
- **widget** (function) - Optional - Widget to render (default: `wibox.widget.textbox`).

### Output
- **widget** (wibox.widget.textbox) - The rendered widget.
- **update** (function) - Function to manually update the widget.
```

--------------------------------

### tp_smapi.installed(batid)

Source: https://github.com/lcpz/lain/wiki/tp_smapi

Checks if the specified battery is currently installed.

```APIDOC
## tp_smapi.installed(batid)

### Description
Checks if the battery `batid` is installed in the system.

### Parameters
- **batid** (string) - The identifier of the battery.

### Returns
- (boolean) True if installed, false otherwise.
```

--------------------------------

### Initialize the file system widget

Source: https://github.com/lcpz/lain/wiki/fs

Basic instantiation of the file system widget.

```lua
local mypartition = lain.widget.fs()
```

--------------------------------

### Configure Quake Client Settings

Source: https://github.com/lcpz/lain/wiki/Utilities

Use the settings function to customize client properties upon spawning.

```lua
-- set the client sticky
s.quake = lain.util.quake { settings = function(c) c.sticky = true end }
```

--------------------------------

### lain.widget.fs(args)

Source: https://github.com/lcpz/lain/wiki/fs

Initializes the file system monitoring widget with optional configuration parameters.

```APIDOC
## lain.widget.fs(args)

### Description
Initializes a new file system widget. If a partition is specified, it triggers a notification when the usage percentage exceeds the threshold.

### Parameters
- **timeout** (integer) - Optional - Refresh timeout in seconds (default: 600)
- **partition** (string) - Optional - Partition to watch for full status
- **threshold** (integer) - Optional - Percentage threshold for notification (default: 99)
- **notification_preset** (table) - Optional - Notification styling settings
- **followtag** (boolean) - Optional - Display notification on focused screen (default: false)
- **showpopup** (string) - Optional - Toggle mouse hover popups ("on" or "off", default: "on")
- **settings** (function) - Optional - User-defined function to format widget output using the `fs_now` table
- **widget** (function) - Optional - Widget rendering function (default: `wibox.widget.textbox`)

### Usage Example
```lua
local mypartition = lain.widget.fs({
    partition = "/home",
    threshold = 90,
    settings = function()
        widget:set_text("Usage: " .. fs_now["/home"].percentage .. "%")
    end
})
```
```

--------------------------------

### Initialize Markup Utility

Source: https://github.com/lcpz/lain/wiki/Utilities

Load the markup utility module for easier text formatting.

```lua
local markup = lain.util.markup
```

--------------------------------

### Initialize and configure the BTinfo widget

Source: https://github.com/lcpz/lain/wiki/btinfo

Instantiate the widget with a specific device MAC address and timeout, using the settings callback to define custom display logic for icons, connectivity status, and battery level colors.

```lua
local btinfo = lain.widget.contrib.btinfo({
      device = "11:22:33:44:55:66", timeout = 30,
      settings = function(bt_now)
         -- Icon type: you might need to install font-awesome to see some of glyphs here.
         local device_glyph=""
         if     bt_now.icon == "audio-headset"    then device_glyph=""
         elseif bt_now.icon == "audio-headphones" then device_glyph=""
         elseif bt_now.icon == "audio-speakers"   then device_glyph="" 
         else                                          device_glyph="?" end

         -- Info text: Make a symbol to summarize the connectivity
         local info_text = ""
         if bt_now.connected and bt_now.paired then info_text = "⧉"
         elseif bw_now.connected               then info_text = "⊚"
         else info_text = "/" end

         -- Battery text: Change the color of widget depending on battery level
         local batt_text = "?"
         local fg_color = "black"
         if     bt_now.percentage >= 90 then fg_color = "#000000"
         elseif bt_now.percentage >= 70 then fg_color = "#110000"
         elseif bt_now.percentage >= 50 then fg_color = "#330000"
         elseif bt_now.percentage >= 30 then fg_color = "#550000"
         elseif bt_now.percentage >= 20 then fg_color = "#aa0000"
         elseif bt_now.percentage >= 10 then fg_color = "#cc0000"
         else                                fg_color = "#ff0000"
         end

         -- and now we put it all together.
         widget:set_markup(markup.fontfg(theme.font, fg_color,
                                         info_text .. device_glyph ..
                                         " " .. tostring(bt_now.percentage) .. "%"))
      end
})
```

--------------------------------

### Initialize Network Widget

Source: https://github.com/lcpz/lain/wiki/net

Basic instantiation of the network monitoring widget.

```lua
local mynet = lain.widget.net()
```

--------------------------------

### Initialize System Load Widget

Source: https://github.com/lcpz/lain/wiki/sysload

Creates a new instance of the system load widget.

```lua
mysysload = lain.widget.sysload()
```

--------------------------------

### Toggle MOC Widget Timer

Source: https://github.com/lcpz/lain/wiki/moc

Keybinding to start or stop the MOC widget timer to save CPU usage.

```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),
```

--------------------------------

### Initialize Quake Dropdown

Source: https://github.com/lcpz/lain/wiki/Utilities

Initialize a Quake-like dropdown container either globally or per-screen.

```lua
local quake = lain.util.quake()
```

```lua
awful.screen.connect_for_each_screen(function(s)
    -- Quake application
    s.quake = lain.util.quake()
    -- [...]
```

--------------------------------

### lain.widget.imap(args)

Source: https://github.com/lcpz/lain/wiki/imap

Initializes a new IMAP widget instance with the provided configuration table.

```APIDOC
## lain.widget.imap(args)

### Description
Creates a new IMAP widget instance that fetches mail counts from a specified server and updates a wibox widget.

### Parameters
#### Required Parameters
- **server** (string) - Mail server address
- **mail** (string) - User email address
- **password** (string|function) - User password or a function to retrieve it
- **widget** (function) - Widget to render (e.g., wibox.widget.textbox)

#### Optional Parameters
- **port** (integer) - IMAP port (default: 993)
- **timeout** (integer) - Refresh interval in seconds (default: 60)
- **pwdtimeout** (integer) - Timeout for password retrieval function (default: 10)
- **is_plain** (boolean) - Whether password is provided as a plain string (default: false)
- **followtag** (boolean) - Whether to show notifications on the focused tag screen (default: false)
- **notify** (string) - Notification popup behavior (default: "on")
- **settings** (function) - User-defined settings function to process mail data

### Usage Example
```lua
local myimap = lain.widget.imap({
    server = "imap.example.com",
    mail = "user@example.com",
    password = "secret",
    is_plain = true,
    widget = wibox.widget.textbox()
})
```
```

--------------------------------

### Initialize CPU widget

Source: https://github.com/lcpz/lain/wiki/cpu

Creates a new instance of the CPU widget for monitoring system usage.

```lua
local mycpu = lain.widget.cpu()
```

--------------------------------

### Toggle MPD widget timer

Source: https://github.com/lcpz/lain/wiki/mpd

Use this key binding to start or stop the MPD widget timer to save CPU usage, with a notification indicating the new state.

```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),
```

--------------------------------

### Initialize IMAP Widget

Source: https://github.com/lcpz/lain/wiki/imap

Basic instantiation of the IMAP widget.

```lua
local myimap = lain.widget.imap(args)
```

--------------------------------

### Create tp_smapi widget

Source: https://github.com/lcpz/lain/wiki/tp_smapi

Creates a widget for monitoring ThinkPad batteries.

```lua
local tpbat = tp_smapi.create_widget()
```

--------------------------------

### lain.widget.net()

Source: https://github.com/lcpz/lain/wiki/net

Initializes the network monitoring widget with optional configuration parameters.

```APIDOC
## lain.widget.net(args)

### Description
Initializes a network monitoring widget that tracks traffic and connection states for specified network interfaces.

### Parameters
- **timeout** (integer) - Optional - Refresh timeout in seconds (default: 2).
- **iface** (string/table) - Optional - Network device(s) to monitor (default: autodetected).
- **units** (integer) - Optional - Units for traffic calculation (default: 1024).
- **notify** (string) - Optional - Toggle "no carrier" notifications (default: "on").
- **wifi_state** (string) - Optional - Enable Wi-Fi connection status tracking (default: "off").
- **eth_state** (string) - Optional - Enable Ethernet connection status tracking (default: "off").
- **screen** (integer) - Optional - Notifications screen index (default: 1).
- **format** (string) - Optional - String format for output (default: "%.1f").
- **settings** (function) - Optional - User-defined function for custom widget logic.

### Methods
- **update()**: Updates the widget display.
- **get_devices()**: Updates the internal interface table.
```

--------------------------------

### lain.widget.contrib.btinfo(args)

Source: https://github.com/lcpz/lain/wiki/btinfo

Initializes the Bluetooth information widget with optional device MAC address and polling timeout.

```APIDOC
## lain.widget.contrib.btinfo(args)

### Description
Initializes a widget that probes the status of a Bluetooth device. The widget provides data to a settings callback function.

### Parameters
- **device** (string) - Optional - The MAC address of the Bluetooth device to probe. If omitted, the default device is used.
- **timeout** (number) - Optional - The polling interval in seconds. If omitted, defaults to 30 seconds.
- **settings** (function) - Optional - A callback function that receives a `bt_now` table containing: `icon`, `connected`, `paired`, and `percentage`.
```

--------------------------------

### Initialize ALSA widget

Source: https://github.com/lcpz/lain/wiki/alsa

Basic instantiation of the ALSA volume widget.

```lua
local volume = lain.widget.alsa()
```

--------------------------------

### Initialize PulseAudio Widget

Source: https://github.com/lcpz/lain/wiki/pulse

Basic initialization of the PulseAudio widget.

```lua
local volume = lain.widget.pulse()
```

--------------------------------

### Configure with Plain Password

Source: https://github.com/lcpz/lain/wiki/imap

Instantiate the widget using a plain text password.

```lua
myimapcheck = lain.widget.imap {
    is_plain = true,
    password = "mymailpassword",
    -- [...]
}
```

--------------------------------

### Initialize Weather Widget

Source: https://github.com/lcpz/lain/wiki/weather

Basic instantiation of the weather widget.

```lua
local myweather = lain.widget.weather()
```

--------------------------------

### Initialize MOC Widget

Source: https://github.com/lcpz/lain/wiki/moc

Basic instantiation of the MOC widget.

```lua
local mymoc = lain.widget.contrib.moc()
```

--------------------------------

### Initialize Temp Widget

Source: https://github.com/lcpz/lain/wiki/temp

Basic instantiation of the temperature widget.

```lua
local mytemp = lain.widget.temp()
```

--------------------------------

### Initialize alsabar widget

Source: https://github.com/lcpz/lain/wiki/alsabar

Basic instantiation of the alsabar widget.

```lua
local volume = lain.widget.alsabar()
```

--------------------------------

### Initialize Battery Widget

Source: https://github.com/lcpz/lain/wiki/bat

Basic instantiation of the battery widget.

```lua
local mybattery = lain.widget.bat()
```

--------------------------------

### Initialize Calendar Widget

Source: https://github.com/lcpz/lain/wiki/cal

Basic instantiation of the calendar widget.

```lua
local mycal = lain.widget.cal()
```

--------------------------------

### tp_smapi.create_widget(args)

Source: https://github.com/lcpz/lain/wiki/tp_smapi

Creates a widget for monitoring ThinkPad batteries.

```APIDOC
## tp_smapi.create_widget(args)

### Description
Creates a lain widget for monitoring ThinkPad batteries.

### Parameters
- **args** (table) - Configuration table containing:
  - **widget** (wibox.widget) - The widget type to use.
  - **timeout** (integer) - Refresh timeout in seconds.
  - **pspath** (string) - Power supply directory path.
  - **battery** (string) - Single battery id.
  - **batteries** (table) - Multiple battery ids.
  - **settings** (function) - User settings function.
```

--------------------------------

### lain.widget.contrib.task.prompt()

Source: https://github.com/lcpz/lain/wiki/task

Opens a promptbox to input and execute a task command.

```APIDOC
## lain.widget.contrib.task.prompt()

### Description
Opens a promptbox allowing the user to input a task command to be executed.
```

--------------------------------

### Download and enable MPD fade script

Source: https://github.com/lcpz/lain/wiki/mpd

Download the fade script to the local bin directory and make it executable to enable volume fading.

```shell
$ curl https://gist.githubusercontent.com/lcpz/76e315bc27c6cdf7edd5021964b88df1/raw/97f7ba586418a4e07637cfbc91d2974278dfa623/mpd-fade -o ~/bin/mpc-fade
$ chmod +x ~/bin/mpc-fade
```

--------------------------------

### lain.widget.temp()

Source: https://github.com/lcpz/lain/wiki/temp

Initializes the CPU temperature widget.

```APIDOC
## lain.widget.temp()

### Description
Initializes and returns a widget that shows the current CPU temperature.

### Constructor
`local mytemp = lain.widget.temp(args)`

### Parameters
- **timeout** (integer) - Optional - Refresh timeout in seconds (Default: 30)
- **tempfile** (string) - Optional - Path to the file storing core temperature (Default: "/sys/devices/virtual/thermal/thermal_zone0/temp")
- **settings** (function) - Optional - User settings function
- **format** (string) - Optional - String format for output (Default: "%.1f")
- **widget** (function) - Optional - Widget to render (Default: wibox.widget.textbox)

### Output
- **widget** (wibox.widget.textbox) - The rendered widget
- **update** (function) - Function to manually update the widget
```

--------------------------------

### Configure Cascade Layout Parameters

Source: https://github.com/lcpz/lain/wiki/Layouts

Set specific tiling offsets and padding for the cascade layout.

```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
```

--------------------------------

### Initialize MPD Widget

Source: https://github.com/lcpz/lain/wiki/mpd

Basic instantiation of the MPD widget.

```lua
local mympd = lain.widget.mpd()
```

--------------------------------

### Initialize tp_smapi interface

Source: https://github.com/lcpz/lain/wiki/tp_smapi

Initializes the tp_smapi interface with an optional API path.

```lua
local tp_smapi = lain.widget.contrib.tp_smapi(apipath)
```

--------------------------------

### Configure with Password Manager

Source: https://github.com/lcpz/lain/wiki/imap

Instantiate the widget using a function to retrieve passwords from a manager.

```lua
myimapcheck = lain.widget.imap {
    password = function()
        -- do your retrieval
        return retrieved_password, try_again
    end,
    -- [...]
}
```

--------------------------------

### Initialize Memory Widget

Source: https://github.com/lcpz/lain/wiki/mem

Instantiate the memory widget using the lain library.

```lua
local mymem = lain.widget.mem()
```

--------------------------------

### lain.widget.mem()

Source: https://github.com/lcpz/lain/wiki/mem

Initializes the memory widget to display system memory status.

```APIDOC
## lain.widget.mem()

### Description
Initializes a memory widget that displays memory status in MiB, similar to the output of 'top' or 'free -h'.

### Constructor
`local mymem = lain.widget.mem(args)`

### Parameters
#### Input Table (args)
- **timeout** (integer) - Optional - Refresh timeout in seconds (Default: 2)
- **settings** (function) - Optional - User settings function (Default: empty function)
- **widget** (function) - Optional - Widget to render (Default: wibox.widget.textbox)

### Settings Variables
Inside the `settings` function, the following variables are available:
- **mem_now.used** (string) - Memory used (MiB)
- **mem_now.swapused** (string) - Swap memory used (MiB)
- **mem_now.perc** (int) - Memory percentage

### Output Table
- **widget** (wibox.widget.textbox) - The rendered widget
- **update** (function) - Function to manually update the widget
```

--------------------------------

### Initialize Watch Widget

Source: https://github.com/lcpz/lain/wiki/watch

Basic instantiation of the lain watch widget.

```lua
local mywatch = lain.widget.watch()
```

--------------------------------

### Initialize Pulsebar Widget

Source: https://github.com/lcpz/lain/wiki/pulsebar

Basic instantiation of the pulsebar widget.

```lua
local volume = lain.widget.pulsebar()
```

--------------------------------

### Initialize Cairo Separators

Source: https://github.com/lcpz/lain/wiki/Utilities

Load the separators utility module.

```lua
local separators = lain.util.separators
```

--------------------------------

### Configure Calendar Widget with Attachments

Source: https://github.com/lcpz/lain/wiki/cal

Initialize the calendar widget with a list of target widgets for interaction.

```lua
local mycal = lain.widget.cal {
    attach_to = { mywidget1, mywidget2, ...  },
    -- [...]
}
```

--------------------------------

### Magnify a client

Source: https://github.com/lcpz/lain/wiki/Utilities

Set a client to floating and resize it similarly to the magnifier layout.

```lua
clientkeys = awful.util.table.join(
    -- [...]
    awful.key({ modkey, "Control" }, "m", lain.util.magnify_client),
    -- [...]
)
```

--------------------------------

### Define volume keybindings

Source: https://github.com/lcpz/lain/wiki/alsa

Set up keyboard shortcuts to control volume levels and muting.

```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),
```

--------------------------------

### Check Network Interfaces

Source: https://github.com/lcpz/lain/wiki/net

Command to list network devices for manual interface configuration.

```shell
ip link show
```

--------------------------------

### lain.widget.bat()

Source: https://github.com/lcpz/lain/wiki/bat

Initializes the battery widget. The widget automatically detects battery and AC power supply paths, but these can be overridden via an input table.

```APIDOC
## lain.widget.bat()

### Description
Initializes a battery monitoring widget that displays remaining time, percentage capacity, and current wattage. It supports multiple batteries and provides notification popups for charging, low, or critical battery states.

### Parameters
#### Input Table
- **timeout** (integer) - Optional - Refresh interval in seconds (default: 30)
- **pspath** (string) - Optional - Power supply directory path (default: "/sys/class/power_supply/")
- **battery** (string) - Optional - Single battery identifier
- **batteries** (table of strings) - Optional - Multiple battery identifiers
- **ac** (string) - Optional - AC power supply identifier
- **notify** (string) - Optional - Enable/disable notifications ("on"/"off", default: "on")
- **full_notify** (string) - Optional - Enable notification when fully charged
- **n_perc** (table of integers) - Optional - Percentages for critical and low levels (default: {5, 15})
- **settings** (function) - Optional - User-defined settings function
- **widget** (function) - Optional - Widget rendering function (default: wibox.widget.textbox)

### Output
- **widget** (wibox.widget.textbox) - The rendered widget instance
- **update** (function) - Function to manually refresh the widget
```

--------------------------------

### Include Lain in rc.lua

Source: https://github.com/lcpz/lain/wiki/Home

Require the library at the beginning of the AwesomeWM configuration file.

```lua
local lain = require("lain")
```

--------------------------------

### Custom PulseAudio Command

Source: https://github.com/lcpz/lain/wiki/pulse

Alternative command configuration using grep if sed is unavailable.

```lua
cmd = "pacmd list-" .. pulse.devicetype .. "s | grep -e $(pactl info | grep -e 'ink' | cut -d' ' -f3) -e 'volume: front' -e 'muted'"
```

--------------------------------

### lain.widget.alsabar()

Source: https://github.com/lcpz/lain/wiki/alsabar

Initializes the alsabar widget. The constructor accepts an optional table of parameters to customize the widget's behavior, appearance, and ALSA command settings.

```APIDOC
## lain.widget.alsabar()

### Description
Creates a new alsabar widget instance to display ALSA volume levels.

### Parameters
- **timeout** (integer) - Optional - Refresh timeout in seconds (default: 5)
- **settings** (function) - Optional - User settings function
- **width** (number) - Optional - Bar width (default: 63)
- **height** (number) - Optional - Bar height (default: 1)
- **margins** (number) - Optional - Bar margins (default: 1)
- **paddings** (number) - Optional - Bar paddings (default: 1)
- **ticks** (boolean) - Optional - Set bar ticks on (default: false)
- **ticks_size** (integer) - Optional - Ticks size (default: 7)
- **tick** (string) - Optional - String for a notification tick (default: "|")
- **tick_pre** (string) - Optional - String for the left notification delimeter (default: "[")
- **tick_post** (string) - Optional - String for the right notification delimeter (default: "]")
- **tick_none** (string) - Optional - String for an empty notification tick (default: " ")
- **cmd** (string) - Optional - ALSA mixer command (default: "amixer")
- **channel** (string) - Optional - Mixer channel (default: "Master")
- **togglechannel** (string) - Optional - Toggle channel
- **colors** (table) - Optional - Bar colors
- **notification_preset** (table) - Optional - Notification preset
- **followtag** (boolean) - Optional - Display notification on currently focused screen (default: false)
```

--------------------------------

### lain.util.magnify_client()

Source: https://github.com/lcpz/lain/wiki/Utilities

Sets a client to floating and resizes it to mimic the magnifier layout.

```APIDOC
### lain.util.magnify_client()
```

--------------------------------

### Create a weather pop-up key binding

Source: https://github.com/lcpz/lain/wiki/weather

Define a keyboard shortcut to trigger the weather pop-up, specifying the timeout in seconds.

```lua
awful.key( { "Mod1" }, "w", function () myweather.show(5) end )
```

--------------------------------

### Configure Cascade Master Window Limit

Source: https://github.com/lcpz/lain/wiki/Layouts

Set the maximum number of windows before resizing occurs in the cascade layout.

```lua
lain.layout.cascade.nmaster = 5
```

--------------------------------

### lain.widget.cpu()

Source: https://github.com/lcpz/lain/wiki/cpu

Initializes the CPU usage widget. This function returns a table containing the widget instance and an update method.

```APIDOC
## lain.widget.cpu()

### Description
Initializes a widget to display current CPU usage, including general usage and per-core statistics.

### Parameters
- **timeout** (integer) - Optional - Refresh timeout in seconds (Default: 2)
- **settings** (function) - Optional - User settings function to process data
- **widget** (function) - Optional - Widget to render (Default: wibox.widget.textbox)

### Usage
```lua
local mycpu = lain.widget.cpu()
```

### Available Data
- **cpu_now.usage** - General CPU usage percentage
- **cpu_now[i].usage** - Usage percentage for the i-th core (i starts at 1)

### Output
- **widget** (wibox.widget.textbox) - The rendered widget
- **update** (function) - Function to manually trigger a widget update
```

--------------------------------

### Create symlink for music directory

Source: https://github.com/lcpz/lain/wiki/mpd

Use a symlink for the music directory if cover art fails to display in notifications when stored on an external partition.

```shell
ln -s /the/real_path_to_your_music/ /home/username/Music
```

--------------------------------

### lain.widget.pulsebar()

Source: https://github.com/lcpz/lain/wiki/pulsebar

Initializes the pulsebar widget. Users can pass an optional table of settings to configure the widget's appearance, refresh rate, and PulseAudio device behavior.

```APIDOC
## lain.widget.pulsebar()

### Description
Creates a new pulsebar widget instance to display PulseAudio volume levels.

### Signature
`local volume = lain.widget.pulsebar(args)`

### Parameters
- **timeout** (integer) - Optional - Refresh timeout in seconds (default: 5)
- **settings** (function) - Optional - User settings function
- **width** (number) - Optional - Bar width (default: 63)
- **height** (number) - Optional - Bar height (default: 1)
- **margins** (number) - Optional - Bar margins (default: 1)
- **paddings** (number) - Optional - Bar paddings (default: 1)
- **ticks** (boolean) - Optional - Set bar ticks on (default: false)
- **ticks_size** (number) - Optional - Ticks size (default: 7)
- **tick** (string) - Optional - String for a notification tick (default: "|")
- **tick_pre** (string) - Optional - Left notification delimiter (default: "[")
- **tick_post** (string) - Optional - Right notification delimiter (default: "]")
- **tick_none** (string) - Optional - String for an empty notification tick (default: " ")
- **scallback** (function) - Optional - PulseAudio sink callback
- **sink** (number) - Optional - Mixer sink (default: 0)
- **colors** (table) - Optional - Bar colors (background, mute, unmute)
- **notification_preset** (table) - Optional - Notification preset
- **followtag** (boolean) - Optional - Display notification on currently focused screen (default: false)
- **devicetype** (string) - Optional - PulseAudio device type ("sink" or "source", default: "sink")
- **cmd** (string/function) - Optional - PulseAudio command
```

--------------------------------

### Create a menu with extra choices

Source: https://github.com/lcpz/lain/wiki/Utilities

Initializes a menu object including an extra choice for cancellation.

```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 }
}
```

--------------------------------

### mypartition.show(seconds, scr)

Source: https://github.com/lcpz/lain/wiki/fs

Manually triggers a notification for the file system widget.

```APIDOC
## mypartition.show(seconds, scr)

### Description
Displays a notification for the file system status. This is typically bound to a key combination.

### Parameters
- **seconds** (integer) - Optional - Duration to display the notification
- **scr** (integer) - Optional - Screen index to display the notification on

### Usage Example
```lua
awful.key({ "Mod1" }, "h", function () mypartition.show(5, 1) end)
```
```

--------------------------------

### Create a menu iterator

Source: https://github.com/lcpz/lain/wiki/Utilities

Initializes a menu object with choices and callbacks for selection and rejection.

```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
}
```

--------------------------------

### lain.widget.alsa()

Source: https://github.com/lcpz/lain/wiki/alsa

Initializes the ALSA volume widget. This function returns a table containing the widget and update methods.

```APIDOC
## lain.widget.alsa()

### Description
Initializes the ALSA volume widget. It accepts a table of configuration parameters to customize the behavior and appearance of the volume display.

### Parameters
- **timeout** (integer) - Optional - Refresh timeout in seconds (default: 5)
- **cmd** (string) - Optional - Alsa mixer command (default: "amixer")
- **channel** (string) - Optional - Mixer channel (default: "Master")
- **togglechannel** (string) - Optional - Channel used for toggling mute
- **settings** (function) - Optional - User settings function to access volume_now.level and volume_now.status
- **widget** (function) - Optional - Widget to render (default: wibox.widget.textbox)

### Returns
- **widget** (wibox.widget.textbox) - The rendered widget
- **channel** (string) - The configured ALSA channel
- **update** (function) - Function to manually trigger a widget update
```

--------------------------------

### Default Settings Function

Source: https://github.com/lcpz/lain/wiki/watch

The default implementation for updating the widget text using the command output.

```lua
settings = function() widget:set_text(output) end
```

--------------------------------

### Define notification preset

Source: https://github.com/lcpz/lain/wiki/fs

Default configuration for the notification appearance.

```lua
notification_preset = {
    font = "Monospace 10",
    fg   = "#FFFFFF",
    bg   = "#000000"
}
```

--------------------------------

### Configure Widget Mouse Buttons

Source: https://github.com/lcpz/lain/wiki/pulse

Assign mouse actions to the widget for volume control and pavucontrol access.

```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 %s 100%%", volume.device))
        volume.update()
    end),
    awful.button({}, 3, function() -- right click
        os.execute(string.format("pactl set-sink-mute %s toggle", volume.device))
        volume.update()
    end),
    awful.button({}, 4, function() -- scroll up
        os.execute(string.format("pactl set-sink-volume %s +1%%", volume.device))
        volume.update()
    end),
    awful.button({}, 5, function() -- scroll down
        os.execute(string.format("pactl set-sink-volume %s -1%%", volume.device))
        volume.update()
    end)
))
```

--------------------------------

### lain.widget.weather()

Source: https://github.com/lcpz/lain/wiki/weather

Initializes the weather widget. Users can pass an input table to configure the widget, including API keys, city IDs, units, and notification settings.

```APIDOC
## lain.widget.weather(args)

### Description
Creates a new weather widget instance. The widget fetches data from OpenWeatherMap and displays it in a textbox, with optional pop-up notifications for forecasts.

### Parameters
- **APPID** (string) - Required - OpenWeatherMap API key.
- **timeout** (number) - Optional - Refresh interval in seconds (default: 900).
- **city_id** (number/string) - Optional - The city ID or name to fetch weather for.
- **units** (string) - Optional - Temperature units: "metric", "imperial", or "standard" (default: "metric").
- **lang** (string) - Optional - Localization code (default: "en").
- **cnt** (integer) - Optional - Number of forecast days (default: 5).
- **icons_path** (string) - Optional - Path to weather icons.
- **notification_preset** (table) - Optional - Naughty notification preset table.
- **followtag** (boolean) - Optional - If true, displays notifications on the currently focused screen (default: false).
- **showpopup** (string) - Optional - Toggle popups: "on" or "off" (default: "on").

### Usage Example
```lua
local myweather = lain.widget.weather({
    APPID = "your_api_key",
    city_id = 2643743,
    units = "metric"
})
```
```

--------------------------------

### lain.widget.pulse()

Source: https://github.com/lcpz/lain/wiki/pulse

Initializes the PulseAudio volume widget. Users can provide an input table to configure the refresh timeout, device type, command execution, and custom rendering settings.

```APIDOC
## lain.widget.pulse(args)

### Description
Creates a new PulseAudio widget instance.

### Parameters
- **timeout** (integer) - Optional - Refresh timeout in seconds (default: 5)
- **devicetype** (string) - Optional - PulseAudio device type, either "sink" or "source" (default: "sink")
- **cmd** (string or function) - Optional - Terminal command or function returning a command string to fetch device info
- **settings** (function) - Optional - User-defined function to process volume data and update the widget
- **widget** (function) - Optional - Widget to render (default: wibox.widget.textbox)

### Output Table
- **widget** (wibox.widget.textbox) - The rendered widget
- **update** (function) - Function to manually trigger a widget update
```

--------------------------------

### lain.widget.watch()

Source: https://github.com/lcpz/lain/wiki/watch

Initializes a new asynchronous watcher widget.

```APIDOC
## lain.widget.watch(args)

### Description
Creates an asynchronous watcher widget that executes a command and updates a wibox widget with the output.

### Parameters
- **widget** (wibox.widget) - Optional - Widget to feed (default: wibox.widget.textbox)
- **timeout** (number) - Optional - Refresh timeout in seconds (default: 5)
- **cmd** (string or table) - Optional - The command to execute
- **nostart** (boolean) - Optional - If true, the widget timer does not start immediately (default: false)
- **stoppable** (boolean) - Optional - If true, the widget timer is stoppable (default: false)
- **settings** (function) - Optional - User settings function that can access the 'output' variable

### Returns
- **widget** (wibox.widget) - The widget instance
- **update** (function) - Function to manually refresh the widget
- **timer** (gears.timer) - The widget timer instance
```

--------------------------------

### lain.widget.mpd()

Source: https://github.com/lcpz/lain/wiki/mpd

Initializes the MPD widget to display status information from a Music Player Daemon server.

```APIDOC
## lain.widget.mpd()

### Description
Initializes a new MPD widget instance. The widget monitors the specified MPD server and can display song information and album art via notifications.

### Parameters
- **timeout** (integer) - Optional - Refresh timeout in seconds (Default: 2)
- **password** (string) - Optional - MPD password (Default: "")
- **host** (string) - Optional - MPD server host (Default: "127.0.0.1")
- **port** (string) - Optional - MPD server port (Default: "6600")
- **music_dir** (string) - Optional - Path to music directory (Default: "~/Music")
- **cover_size** (integer) - Optional - Album art notification size (Default: 100)
- **cover_pattern** (string) - Optional - Pattern for album art file (Default: "*.(jpg|jpeg|png|gif)$")
- **default_art** (string) - Optional - Default art path (Default: nil)
- **notify** (string) - Optional - Enable notification pop-ups (Default: "on")
- **followtag** (boolean) - Optional - Notification behavior (Default: false)
- **settings** (function) - Optional - User settings function to access `mpd_now` table
- **widget** (function) - Optional - Widget to render (Default: wibox.widget.textbox)

### Usage Example
```lua
local mympd = lain.widget.mpd({
    timeout = 5,
    host = "127.0.0.1",
    port = "6600"
})
```
```

--------------------------------

### Temperature File Paths

Source: https://github.com/lcpz/lain/wiki/temp

Standard paths used for retrieving core temperature data on GNU/Linux systems.

```shell
/sys/class/devices/virtual/thermal/thermal_zone*
/sys/class/devices/platform/coretemp*/hwmon/hwon*
```

--------------------------------

### lain.widget.contrib.moc()

Source: https://github.com/lcpz/lain/wiki/moc

Initializes the MOC widget. The function accepts an input table to configure behavior such as refresh timeout, music directory, and notification settings.

```APIDOC
## lain.widget.contrib.moc(args)

### Description
Creates a new MOC widget instance.

### Parameters
- **timeout** (integer) - Optional - Refresh timeout in seconds (default: 1)
- **music_dir** (string) - Optional - Music directory (default: "~/Music")
- **cover_size** (integer) - Optional - Album art notification size (default: 100)
- **cover_pattern** (string) - Optional - Pattern for album art file (default: "*\\.(jpg|jpeg|png|gif)")
- **default_art** (string) - Optional - Default art path (default: "")
- **followtag** (boolean) - Optional - Display notification on focused screen (default: false)
- **settings** (function) - Optional - User settings function
- **widget** (function) - Optional - Widget to render (default: wibox.widget.textbox)

### Example
```lua
local mymoc = lain.widget.contrib.moc({
    timeout = 5,
    music_dir = "~/Music"
})
```
```

--------------------------------

### Configure alsabar buttons

Source: https://github.com/lcpz/lain/wiki/alsabar

Add mouse button bindings to the alsabar widget in rc.lua to control volume and launch mixers.

```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)
))
```

--------------------------------

### lain.util.menu_clients_current_tags(menu_args, options)

Source: https://github.com/lcpz/lain/wiki/Utilities

Displays a menu of clients currently visible on the active tags.

```APIDOC
### lain.util.menu_clients_current_tags(menu_args, options)

**Parameters:**
- **menu_args** (table) - Required - Menu configuration table (e.g., width).
- **options** (table) - Required - Menu options (e.g., keygrabber).
```

--------------------------------

### Menu for clients on current tags

Source: https://github.com/lcpz/lain/wiki/Utilities

Display a menu containing only clients from currently visible tags.

```lua
awful.key({ "Mod1" }, "Tab", function()
    lain.util.menu_clients_current_tags({ width = 350 }, { keygrabber = true })
end),
```

--------------------------------

### Configure Termfair Layout Columns and Rows

Source: https://github.com/lcpz/lain/wiki/Layouts

Set the number of master columns and total columns for termfair-based layouts.

```lua
lain.layout.termfair.nmaster = 3
lain.layout.termfair.ncol    = 1
```

--------------------------------

### Configure Shell Command

Source: https://github.com/lcpz/lain/wiki/watch

Format for executing commands that require a shell environment.

```lua
cmd = { awful.util.shell, "-c", "myactualcommand" }
```

--------------------------------

### myweather.show(timeout)

Source: https://github.com/lcpz/lain/wiki/weather

Displays the weather pop-up for a specified duration.

```APIDOC
## myweather.show(timeout)

### Description
Triggers the weather pop-up display. This is typically used within key bindings.

### Parameters
- **timeout** (integer) - Required - The duration in seconds for which the pop-up will be shown.
```

--------------------------------

### lain.menu_iterator.menu

Source: https://github.com/lcpz/lain/wiki/Utilities

Creates a menu object with defined choices, callbacks, and configuration.

```APIDOC
## lain.menu_iterator.menu

### Description
Creates a menu object that can be used with the iterate function. It accepts a table of configuration options including choices, callbacks, and menu behavior.

### Parameters
- **choices** (array of strings) - Required - List of choices available in the menu.
- **name** (string) - Required - Name of the program related to this menu.
- **selected_cb** (function) - Optional - Callback to execute for the selected choice.
- **rejected_cb** (function) - Optional - Callback to execute for all rejected choices.
- **extra_choices** (array of {choice, callback}) - Optional - Additional choices that do not trigger the rejected_cb.
- **combination** (string) - Optional - How choices are combined: "single" (default) or "powerset".
```

--------------------------------

### Configure Cascade Layout Offsets

Source: https://github.com/lcpz/lain/wiki/Layouts

Adjust the horizontal and vertical offsets for the cascade layout.

```lua
lain.layout.cascade.offset_x = 64
lain.layout.cascade.offset_y = 16
```

--------------------------------

### lain.util.menu_iterator.iterate(menu)

Source: https://github.com/lcpz/lain/wiki/Utilities

Iterates over a list of actions to execute.

```APIDOC
### lain.util.menu_iterator.iterate(menu)

**Parameters:**
- **menu** (table) - Required - A table of choices in the format `{ { "description", callback }, ... }`.
```

--------------------------------

### Set Single Client Gap Geometry

Source: https://github.com/lcpz/lain/wiki/Layouts

Define window geometry for single-client scenarios in theme configuration.

```lua
theme.single_gap = { width = 600, height = 100 }
```
Tokens:
Raw