### Clone Lain Repository using Git

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

This command clones the Lain project repository from GitHub into the specified directory in the user's configuration folder. This is a common method for installing custom configurations or libraries for the Awesome Window Manager.

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

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

### Example Temperature File Paths (Shell)

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

Demonstrates example file paths on a GNU/Linux system where core temperature values are stored. These paths are used by the lain.widget.temp module to read temperature data.

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

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

### Install Lain Locally with Luarocks

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

Forks the Lain repository, clones it locally, and installs it as a user package using luarocks. This ensures that only your local development version is installed, overwriting any existing installation.

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

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

### Install Lain using LuaRocks

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

This command installs the Lain library using LuaRocks, the package manager for Lua. This is a convenient way to install Lain if you have LuaRocks set up on your system.

```shell
luarocks install lain
```

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

### IMAP Widget Usage

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

This section describes how to use the IMAP widget and provides an example of its initialization.

```APIDOC
## Usage

Shows mails count fetching over IMAP.

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

New mails are notified like this:

	+--------------------------------------------+
	| +---+                                      |
	| |\ /| donald@disney.org has 3 new messages |
	| +---+                                      |
	+--------------------------------------------+

## Input table

Required parameters are:

Variable | Meaning | Type
--- | --- | ---
`server` | Mail server | string
`mail` | User mail | string
`password` | User password | string
`widget` | Widget to render | function | `wibox.widget.textbox`

while the optional are:

Variable | Meaning | Type | Default
--- | --- | --- | ---
`port` | IMAP port | integer | 993
`timeout` | Refresh timeout (in seconds) | integer | 60
`pwdtimeout` | Timeout for password retrieval function (see [here](https://github.com/lcpz/lain/wiki/imap#password-security)) | integer | 10
`is_plain` | Define whether `password` is a plain password (true) or a command that retrieves it (false) | boolean | false
`followtag` | Notification behaviour | boolean | false
`notify` | Show notification popups | string | "on"
`settings` | User settings | function | empty function

`settings` can use `imap_now` table, which contains the following non negative integers:

- `["MESSAGES"]`
- `["RECENT"]`
- `["UNSEEN"]`

example of fetch: `total = imap_now["MESSAGES"]`. For backwards compatibility, `settings` can also use `mailcount`, a pointer to `imap_now["UNSEEN"]`.

Also, `settings` can modify `mail_notification_preset` table, which will be the preset for the naughty notifications. Check [here](https://awesomewm.org/apidoc/libraries/naughty.html#notify) for the list of variables it can contain. Default definition:

```lua
mail_notification _preset = {
    icon = "lain/icons/mail.png",
    position = "top_left"
}
```

Note that `mailcount` and `imap_now` elements are equals to 0 either if there are no new mails or credentials are invalid, so make sure that your settings are correct.

With multiple screens, the default behaviour is to show a visual notification pop-up window on the first screen. By setting `followtag` to `true` it will be shown on the currently focused tag screen.

You can have multiple instances of this widget at the same time.
```

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

### Initialize Lain File System Widget

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

Initializes the Lain file system widget. This is the basic setup for the widget, without any specific configurations for partitions or notifications.

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

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

### CPU Widget Usage

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

This section describes how to use the CPU widget to display general and per-core CPU usage. It includes an example of how to initialize the widget and explanations of its input and output parameters.

```APIDOC
## CPU Widget Usage

### Description

Shows the current CPU usage, both in general and per core.

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

### Input Table

| Variable  | Meaning                        | Type     | Default        |
|-----------|--------------------------------|----------|----------------|
| `timeout` | Refresh timeout (in seconds)   | integer  | 2              |
| `settings`| User settings                  | function | empty function |
| `widget`  | Widget to render               | function | `wibox.widget.textbox` |

`settings` can use these strings:

* `cpu_now.usage`, the general use percentage;
* `cpu_now[i].usage`, the i-th core use percentage, with `i` starting from 1.

### Output Table

| Variable | Meaning      | Type             |
|----------|--------------|------------------|
| `widget` | The widget   | `wibox.widget.textbox` |
| `update` | Update `widget`| function         |
```

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

### Initialize Lain Weather Widget

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

Initializes the Lain weather widget. This is the primary step to start using the weather functionality. No specific dependencies are mentioned beyond the Lain library itself.

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

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

### Initialize Lain Network Widget

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

Initializes the Lain network widget to monitor network traffic. This is the basic setup for using the widget.

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

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

### Initialize Lain ALSA Volume Widget

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

Initializes the ALSA volume widget from the lain library. This is the primary step to start using the widget.

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

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

### Retrieve Current Weather Data Example

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

An example demonstrating how to retrieve and format current weather data within a custom `settings` function. It accesses the `weather_now` table, which is populated by the `current_call`, to extract the weather description and temperature. This showcases dynamic data retrieval and formatting.

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

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

### Bitcoin Price Widget Example

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

An example demonstrating how to use the Lain 'watch' widget to fetch and display the current Bitcoin to USD price using the Coinbase API. It includes custom settings to decode the JSON output and update the widget text. The timeout is set to half a day.

```lua
-- Bitcoin to USD current price, using Coinbase V1 API
local bitcoin = lain.widget.watch({
    timeout = 43200, -- half day
    stoppable = true,
    cmd = "curl -m5 -s 'https://coinbase.com/api/v1/prices/buy'",
    settings = function()
        local btc, pos, err = require("lain.util").dkjson.decode(output, 1, nil)
        local btc_price = (not err and btc and btc["subtotal"]["amount"]) or "N/A"

        -- customize here
        widget:set_text(btc_price)
    end
})
```

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

### Include Lain in AwesomeWM rc.lua

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

This Lua code snippet demonstrates how to require and load the Lain library within an Awesome Window Manager configuration file (`rc.lua`). This is the first step to using Lain's features.

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

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

### Initialize PulseAudio Volume Widget (Lua)

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

Initializes the PulseAudio volume widget for Lain. This is the basic setup required to use the widget, setting up the necessary Lua environment.

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

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

### Initialize Lain System Load Widget (Lua)

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

This snippet demonstrates how to initialize the system load widget using Lain. It requires the 'lain' library and provides a basic setup for displaying system load.

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

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

### Configure AwesomeWM to Load Local Lain Package

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

Adds the local user luarocks directory to AwesomeWM's package.path. This allows AwesomeWM to find and load the locally installed Lain library for development.

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

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

### Initialize CPU Temperature Widget (Lua)

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

Initializes the CPU temperature widget. This is a basic setup requiring no additional dependencies beyond the lain library itself. The output is a widget object ready for rendering.

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

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

### Btrfs Filesystem Usage Widget Example

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

This example shows how to use the Lain 'watch' widget to monitor Btrfs filesystem usage. It executes the 'btrfs filesystem df -g /' command, parses the output to extract total and used space, calculates the percentage used, and updates the widget accordingly. The refresh timeout is set to 600 seconds.

```lua
-- btrfs root df
local myrootfs = lain.widget.watch({
    timeout = 600,
    cmd = "btrfs filesystem df -g /",
    settings  = function()
        local total, used  = string.match(output, "Data.-total=(%d+%.%d+)GiB.-used=(%d+%.%d+)GiB")
        local percent_used = math.ceil((tonumber(used) / tonumber(total)) * 100)

        -- customize here
        widget:set_text(" [/: " .. percent_used .. "%] ")
    end
})
```

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

### Rebuild Lain After Code Changes

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

Command to rebuild and reinstall the Lain library locally after making code modifications. This is essential because AwesomeWM loads the installed package, not the source directory directly.

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

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

### Configure Lain File System Widget with Custom Settings

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

Example of configuring the Lain file system widget with custom settings. This demonstrates how to use the `settings` function to dynamically update the widget's text based on file system information, such as the percentage of used space and remaining free space for the home partition.

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

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

### Example Alsamixer Scontents Output

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

Demonstrates the output of the 'amixer scontents' command, which is used to identify device IDs for configuring the togglechannel in the Lain ALSA volume widget. This helps in setting up mute toggling for specific devices like S/PDIF.

```shell
$ amixer -c 1 scontents
Simple mixer control 'Master',0
  Capabilities: volume
  Playback channels: Front Left - Front Right
  Capture channels: Front Left - Front Right
  Limits: 0 - 255
  Front Left: 255 [100%]
  Front Right: 255 [100%]
Simple mixer control 'IEC958',0
  Capabilities: pswitch pswitch-joined
  Playback channels: Mono
  Mono: Playback [on]
Simple mixer control 'IEC958',1
  Capabilities: pswitch pswitch-joined
  Playback channels: Mono
  Mono: Playback [on]
Simple mixer control 'IEC958',2
  Capabilities: pswitch pswitch-joined
  Playback channels: Mono
  Mono: Playback [on]
Simple mixer control 'IEC958',3
  Capabilities: pswitch pswitch-joined
  Playback channels: Mono
  Mono: Playback [on]
```

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

### Show lain.widget.cal with keybinding

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

This snippet illustrates how to set up a keybinding to display the calendar notification using the `mycal.show()` function. The example shows how to trigger the calendar with a 7-second timeout when a specific key combination (e.g., Alt + C) is pressed.

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

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

### MPD Widget Key Bindings

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

Provides example key bindings for controlling MPD playback and toggling the MPD widget's visibility.

```APIDOC
## MPD Widget Key Bindings

### Description
Defines key bindings for common MPD playback controls (toggle, stop, next, previous) and for enabling/disabling the MPD widget to save resources.

### Method
Key binding configuration in Lua

### Endpoint
N/A (Local script execution)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```lua
-- MPD playback controls
awful.key({ altkey, "Control" }, "Up", function () awful.spawn.with_shell("mpc toggle || ncmpc toggle || pms toggle"); mympd.update() end)
awful.key({ altkey, "Control" }, "Down", function () awful.spawn.with_shell("mpc stop || ncmpc stop || pms stop"); mympd.update() end)
awful.key({ altkey, "Control" }, "Left", function () awful.spawn.with_shell("mpc prev || ncmpc prev || pms prev"); mympd.update() end)
awful.key({ altkey, "Control" }, "Right", function () awful.spawn.with_shell("mpc next || ncmpc next || pms next"); mympd.update() end)

-- Toggle MPD widget visibility
local altkey = "Mod1"
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)
```

### Response
#### Success Response (200)
N/A (Key bindings are registered internally)

#### Response Example
N/A
```

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

### Maildir New Mail Notification Widget Example

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

This example uses the Lain 'watch' widget to check for new emails in Maildir directories. It scans specified Maildir structures, counts new emails in each subdirectory, and displays a summary. The command uses 'ls' to find new files, and the settings function parses the output to generate a digest string. The timeout is set to 60 seconds.

```lua
-- checks whether there are files in the "new" directories of a mail dirtree
local mailpath = "~/Mail"
local mymaildir = lain.widget.watch({
    timeout = 60,
    stoppable = true,
    cmd = { awful.util.shell, "-c", string.format("ls -1dr %s/*/new/*", mailpath) },
    settings = function()
        local inbox_now = { digest = "" }

        for dir in output:gmatch(".-/(%w+)/new") do
            inbox_now[dir] = 1
            for _ in output:gmatch(dir) do
                inbox_now[dir] = inbox_now[dir] + 1
            end
            if #inbox_now.digest > 0 then inbox_now.digest = inbox_now.digest .. ", " end
            inbox_now.digest = inbox_now.digest .. string.format("%s (%d)", dir, inbox_now[dir])
        end

        -- customize here
        widget:set_text("mail: " .. inbox_now.digest)
    end
})
```

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

### Display Lain fs Widget Notification

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

Example of how to display the notification generated by the Lain file system widget using a key binding. The `show` function can optionally take arguments for the notification duration in seconds and the target screen.

```lua
awful.key({ altkey }, "h", function () mypartition.show(seconds, scr) end),
where ``altkey = "Mod1"`` and ``show`` arguments, both optionals, are:

* `seconds`, notification time in seconds
* `scr`, screen which to display the notification in
```

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

### Configure and Create tp_smapi Battery Widget in Lua

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

A detailed example of creating a custom battery widget using `tp_smapi.create_widget`. It demonstrates how to specify a particular battery, define custom update logic using `settings`, and connect mouse events to show/hide 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)
```

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

### PulseAudio Volume Widget with Custom Settings (Lua)

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

An example of configuring the PulseAudio volume widget with custom settings, specifically for displaying the volume level and device name, and indicating mute status. It uses `lain.util.markup` for formatting the output.

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

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

### Check if tp_smapi Battery is Installed in Lua

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

Verifies if a specific battery is currently installed and recognized by the system. The function returns a boolean value: true if installed, false otherwise.

```lua
local is_installed = tp_smapi.installed(batid)
```

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

### Quake Dropdown Container Custom Settings (Lua)

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

Demonstrates how to apply custom settings to the Quake dropdown container using the `settings` parameter during initialization. This allows for fine-grained control over the spawned client's properties.

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

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

### Prompt for Taskwarrior Command with Keybinding

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

Sets up a keybinding to open a prompt for entering Taskwarrior commands. This enables interactive command execution through the widget. It utilizes the 'lain' library for prompt functionality. Requires the 'awful' and 'lain' libraries.

```lua
awful.key({ altkey }, "t", lain.widget.contrib.task.prompt)
```

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

### Cmus Audio Player Widget Example

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

An example of using the Lain 'watch' widget to display information about the currently playing track in the cmus audio player. It executes 'cmus-remote -Q', parses the output to extract artist and title, and updates the widget. The widget is set to be stoppable with a 2-second refresh timeout.

```lua
-- cmus audio player
local cmus = lain.widget.watch({
    timeout = 2,
    stoppable = true,
    cmd = "cmus-remote -Q",
    settings = function()
        local cmus_now = {
            state   = "N/A",
            artist  = "N/A",
            title   = "N/A",
            album   = "N/A"
        }

        for w in string.gmatch(output, "(.-)tag") do
            a, b = w:match("(%w+) (.-)\n")
            cmus_now[a] = b
        end

        -- customize here
        widget:set_text(cmus_now.artist .. " - " .. cmus_now.title)
    end
})
```

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

### MOC Widget Output and Control

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

Details the output variables provided by the MOC widget and explains how to use keybindings for controlling music playback and the widget itself.

```APIDOC
## MOC Widget Output and Control

### Output Table

| Variable | Meaning        |
|----------|----------------|
| `widget` | The widget     |
| `update` | Update `widget`|
| `timer`  | The widget timer|

The `update` function can be used to refresh the widget before `timeout` expires.

You can use `timer` to start/stop the widget as you like.

### Keybindings

You can control the widget with key bindings like these:

```lua
-- MOC control
awful.key({ altkey, "Control" }, "Up",
	function ()
		os.execute("mocp -G") -- toggle
		moc.update()
	end),
awful.key({ altkey, "Control" }, "Down",
	function ()
		os.execute("mocp -s") -- stop
		moc.update()
	end),
awful.key({ altkey, "Control" }, "Left",
	function ()
		os.execute("mocp -r") -- previous
		moc.update()
	end),
awful.key({ altkey, "Control" }, "Right",
	function ()
		os.execute("mocp -f") -- next
		moc.update()
	end),
```

where `altkey = "Mod1"`.

If you don't use the widget for long periods and wish to spare CPU, you can toggle it with a keybinding like this:

```lua
-- toggle MOC widget
awful.key({ altkey }, "0",
        function ()
            local common = { text = "MOC widget ", position = "top_middle", timeout = 2 }
            if moc.timer.started then
                moc.timer:stop()
                common.text = common.text .. markup.bold("OFF")
            else
                moc.timer:start()
                common.text = common.text .. markup.bold("ON")
            end
            naughty.notify(common)
        end),
```
```

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

### Arrow Separator Usage (Lua)

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

Example usage of the `arrow_left` and `arrow_right` separator functions. These functions allow for the creation of arrow-shaped separators with customizable colors.

```lua
arrl_dl = separators.arrow_left(beautiful.bg_focus, "alpha")
```

```lua
arrl_ld = separators.arrow_left("alpha", beautiful.bg_focus)
```

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

### Get tp_smapi Battery Percentage in Lua

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

Fetches the current charge percentage of a battery. The function returns a numeric string representing the battery's charge level.

```lua
local percentage = tp_smapi.percentage(batid)
```

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

### Get tp_smapi Battery Status in Lua

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

Retrieves the current operational status of a battery. The function returns a string indicating whether the battery is 'charging', 'discharging', or 'full'.

```lua
local status = tp_smapi.status(batid)
```

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

### Quake Dropdown Container Initialization (Lua)

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

Initializes a Quake-like dropdown container. It can be defined globally for all screens or per-screen. Usage involves calling `lain.util.quake()` with optional configuration parameters.

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

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

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

### Initialize Lain CPU Widget

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

Initializes the Lain CPU widget, which is used to display CPU usage. The widget can be configured via an input table to control refresh rate and user settings. It outputs a widget and an update function.

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

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

### MOC Widget Usage and Configuration

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

Provides information on how to integrate and configure the MOC widget, including input parameters for customization.

```APIDOC
## MOC Widget

### Description
A widget for showing the current song track's information from MOC (Music On Console).

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

### Input Table

| Variable        | Meaning                                      | Type     | Default        |
|-----------------|----------------------------------------------|----------|----------------|
| `timeout`       | Refresh timeout (in seconds)                 | integer  | 1              |
| `music_dir`     | Music directory                              | string   | "~/Music"    |
| `cover_size`    | Album art notification size (height/width)   | integer  | 100            |
| `cover_pattern` | Pattern for the album art file               | string   | `*\\.(jpg|jpeg|png|gif)`* |
| `default_art`   | Default art                                  | string   | ""           |
| `followtag`     | Display notification on focused screen       | boolean  | false          |
| `settings`      | User settings function                       | function | empty function |
| `widget`        | Widget to render                             | function | `wibox.widget.textbox` |

*In Lua, `\\` means `\` escaped.

Default `cover_pattern` definition will make the widget set the first jpg, jpeg, png or gif file found in the directory as the album art.

Pay attention to case sensitivity when defining `music_dir`.

`settings` can use `moc_now` table, which contains the following string values:
- state (possible values: "PLAY", "PAUSE", "STOP")
- file
- artist
- title
- album
- elapsed (Time elapsed for the current track)
- total (The current track's total time)

and can modify `moc_notification_preset` table, which will be the preset for the naughty notifications. Check [here](https://awesomewm.org/apidoc/libraries/naughty.html#notify) for the list of variables it can contain. Default definition:

```lua
moc_notification_preset = {
    title   = "Now playing",
    timeout = 6,
    text    = string.format("%s (%s) - %s\n%s", moc_now.artist,
              moc_now.album, moc_now.elapsed, moc_now.title)
}
```

With multiple screens, the default behaviour is to show a visual notification pop-up window on the first screen. By setting `followtag` to `true` it will be shown on the currently focused tag screen.
```

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

### Initialize lain.widget.cal

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

This snippet shows the basic initialization of the lain.widget.cal widget. It creates an instance of the calendar widget, which can then be further configured or attached to other widgets.

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

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

### Get tp_smapi Battery Time in Lua

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

Retrieves the estimated time remaining for a battery, either for discharging (time left) or charging (time to full). The output is a string formatted as 'HH:MM'.

```lua
local time_info = tp_smapi.time(batid)
```

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

### Markup Utility Initialization (Lua)

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

Initializes the markup utility from the lain library. This provides functions for easily applying text formatting such as bold, italics, colors, and fonts.

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

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

### MPD Notification Preset Configuration (Lua)

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

Defines a custom preset for MPD notifications using the 'naughty' library. This example formats the notification to include the artist, album, date, and title of the currently playing song.

```lua
mpd_notification_preset = {
   title   = "Now playing",
   timeout = 6,
   text    = string.format("%s (%s) - %s\n%s", mpd_now.artist,
             mpd_now.album, mpd_now.date, mpd_now.title)
}
```

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

### tp_smapi Initialization

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

Initializes the tp_smapi module. An optional API path can be provided.

```APIDOC
## tp_smapi Module

### Description
Initializes the tp_smapi interface and widget creator.

### Method
`tp_smapi(apipath)`

### Parameters
#### Path Parameters
- **apipath** (string) - Optional - Defines the API path. Defaults to `"/sys/devices/platform/smapi"`.

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

### Response
#### Success Response
- **tp_smapi** (module) - The initialized tp_smapi module.

#### Response Example
```lua
local tp_smapi = require("lain.widget.contrib.tp_smapi")
```
```

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

### Get tp_smapi Battery Feature in Lua

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

Retrieves a specific feature's value for a given battery. The function returns a string representing the feature's status. A comprehensive list of supported features can be found in the ThinkWiki documentation.

```lua
local feature_value = tp_smapi.get(batid, feature)
```

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

### Initialize MOC Widget (Lua)

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

Initializes the MOC widget, which displays the current song track information from MOC. It takes configuration options like refresh timeout, music directory, and album art size.

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

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

### Magnify Client Utility with lain (Lua)

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

Sets a client to floating and resizes it like the 'magnifier' layout. Places the magnified client on the current screen derived from mouse position. Retyping the keybinding de-magnifies the client.

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

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

### Initialize Lain Watch Widget

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

Demonstrates the basic initialization of a Lain 'watch' widget. This widget is designed to execute a command and display its output in a wibox widget asynchronously. It's a wrapper around AwesomeWM's 'awful.widget.watch'.

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

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

### Initialize PulseAudio Volume Widget

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

Initializes the PulseAudio volume widget from the 'lain' library. This widget displays the system's audio volume using a progress bar and supports custom notifications and tooltips.

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

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

### Modified Current Weather API Call (by City Name)

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

An example of a modified `curl` command to fetch current weather data by city name instead of city ID. This demonstrates flexibility in querying the OpenWeatherMap API by replacing `id` with `q` and suggests setting `city_id` to the city name.

```bash
"curl -s 'http://api.openweathermap.org/data/2.5/weather?q=%s&units=%s&lang=%s&APPID=%s'"
```

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

### Pulsebar Widget Configuration

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

Configuration options for the PulseAudio volume widget with a progress bar.

```APIDOC
## Lain Pulsebar Widget Configuration

### Description

This widget displays PulseAudio volume with a progress bar, providing tooltips and notifications. It can be initialized with `local volume = lain.widget.pulsebar()`.

### Parameters

#### Input Table

- **timeout** (integer) - Optional - Refresh timeout in seconds. Default: 5
- **settings** (function) - Optional - User settings function. Default: empty function
- **width** (number) - Optional - Width of the progress bar. Default: 63
- **height** (number) - Optional - Height of the progress bar. Default: 1
- **margins** (number) - Optional - Margins for the bar. Default: 1
- **paddings** (number) - Optional - Paddings for the bar. Default: 1
- **ticks** (boolean) - Optional - Whether to show ticks on the bar. Default: false
- **ticks_size** (number) - Optional - Size of the ticks. Default: 7
- **tick** (string) - Optional - String for a notification tick. Default: "|"
- **tick_pre** (string) - Optional - String for the left notification delimiter. Default: "["
- **tick_post** (string) - Optional - String for the right notification delimiter. Default: "]"
- **tick_none** (string) - Optional - String for an empty notification tick. Default: " "
- **scallback** (function) - Optional - PulseAudio sink callback. See [pulseauido wiki](https://github.com/lcpz/lain/wiki/pulseaudio/). Default: `nil`
- **sink** (number) - Optional - Mixer sink identifier. Default: 0
- **colors** (table) - Optional - Bar colors. See [Default colors](#default-colors). Default: see [Default colors](https://github.com/lcpz/lain/wiki/pulsebar#default-colors)
- **notification_preset** (table) - Optional - Notification preset configuration. See [default `notification_preset`](https://github.com/lcpz/lain/wiki/pulsebar#default-notification_preset). Default: See [default `notification_preset`](https://github.com/lcpz/lain/wiki/pulsebar#default-notification_preset)
- **followtag** (boolean) - Optional - Display notification on the currently focused tag screen. Default: false
- **devicetype** (string) - Optional - PulseAudio device type ("sink" or "source"). Default: "sink"
- **cmd** (string or function) - Optional - PulseAudio command configuration. See [here](https://github.com/lcpz/lain/blob/master/widget/pulsebar.lua#L48). Default: see [here](https://github.com/lcpz/lain/blob/master/widget/pulsebar.lua#L48)

#### Default Colors

- **background** (string) - Bar background color. Default: "#000000"
- **mute** (string) - Bar mute color. Default: "#EB8F8F"
- **unmute** (string) - Bar unmute color. Default: "#A4CE8A"

#### Default `notification_preset`

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

### Output Table

- **bar** (`wibox.widget.progressbar`) - The progress bar widget.
- **device** (string) - The PulseAudio device identifier.
- **notify** (function) - Function to trigger a notification.
- **update** (function) - Function to update the widget state.
- **tooltip** (`awful.tooltip`) - The tooltip associated with the widget.

### Buttons

- Left Click (1): Opens `pavucontrol`.
- Middle Click (2): Sets sink volume to 100% and updates the widget.
- Right Click (3): Toggles sink mute and updates the widget.
- Scroll Up (4): Increases sink volume by 1% and updates the widget.
- Scroll Down (5): Decreases sink volume by 1% and updates the widget.

### Keybindings

Similar to the [pulse wiki keybindings](https://github.com/lcpz/lain/wiki/pulse#keybindings). Use `volume.notify()` for notifications instead of `volume.update()`.
```

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

### Configure Termfair Layout Columns and Rows (Lua)

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

Configures the termfair layout to use a specific number of columns and master windows. The `nmaster` variable sets the number of columns for master windows, and `ncol` sets the number of columns for slave windows. Defaults are usually taken from `awful.tag`.

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

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

### CPU Temperature Widget

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

Displays the current CPU temperature using system files. Allows customization of refresh rate, temperature file path, output format, and widget type.

```APIDOC
## CPU Temperature Widget

### Description

Shows the current CPU temperature.

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

### Method

GET (conceptual, as it's a widget configuration)

### Endpoint

N/A (widget configuration)

### Parameters

#### Input Table

- **timeout** (integer) - Optional - Refresh timeout in seconds (default: 30)
- **tempfile** (string) - Optional - Path of the file storing core temperature value (default: "/sys/devices/virtual/thermal/thermal_zone0/temp")
- **settings** (function) - Optional - User settings function. Can use `coretemp_now` and `temp_now`.
- **format** (string) - Optional - String format for output (default: "%.1f")
- **widget** (function) - Optional - Widget to render (default: `wibox.widget.textbox`)

### Request Example

```lua
local temp_widget = lain.widget.temp({
    timeout = 10,
    format = "%.2f°C",
    tempfile = "/sys/class/thermal/thermal_zone1/temp"
})
```

### Response

#### Success Response (200)

- **widget** (`wibox.widget.textbox`) - The rendered widget.
- **update** (function) - A function to update the widget.

#### Response Example

```json
{
  "widget_content": "55.5",
  "last_updated": "2023-10-27T10:30:00Z"
}
```
```

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

### Initialize Lain IMAP Widget

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

Initializes the IMAP widget to display mail counts. It requires basic IMAP credentials and a widget to render. Optional parameters control refresh rate, notifications, and password retrieval.

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

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

### Quake Dropdown Container Keybinding (Lua)

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

Defines keybindings to toggle the Quake dropdown container. The implementation differs slightly based on whether a global or per-screen instance of the Quake container is used.

```lua
awful.key({ modkey, }, "z", function () quake:toggle() end),
```

```lua
awful.key({ modkey, }, "z", function () awful.screen.focused().quake:toggle() end),
```

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

### Configure lain.widget.cal with attach_to

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

This snippet demonstrates how to configure the lain.widget.cal widget by specifying which widgets it should be attached to. The `attach_to` parameter takes a table of widgets, enabling interactions like month navigation via mouse clicks or scrolls on these widgets.

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

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

### Awesome WM Client Focus by Direction Keybindings

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

Defines keybindings for navigating between windows in Awesome WM using directional focus. It suggests using `awful.client.focus.bydirection()` for layouts like 'centerwork' where window focus can be confusing. If a client gains focus, it's raised to the top.

```lua
globalkeys = awful.util.table.join(
    -- [...]
    awful.key({ modkey }, "j",
        function()
            awful.client.focus.bydirection("down")
            if client.focus then client.focus:raise() end
        end),
    awful.key({ modkey }, "k",
        function()
            awful.client.focus.bydirection("up")
            if client.focus then client.focus:raise() end
        end),
    awful.key({ modkey }, "h",
        function()
            awful.client.focus.bydirection("left")
            if client.focus then client.focus:raise() end
        end),
    awful.key({ modkey }, "l",
        function()
            awful.client.focus.bydirection("right")
            if client.focus then client.focus:raise() end
        end),
    -- [...]
)
```

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

### Generic Menu Iterator with lain (Lua)

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

A utility for creating menus that iterate over lists of actions. Can be used to create dynamic menus for configurations like xrandr. Requires a table defining choices and callbacks.

```lua
-- Example menu definition table
{
  { "choice description 1", callbackFuction1 },
  { "choice description 2", callbackFunction2 },
  ...
}
```

```lua
-- Example usage with lain.menu_iterator.menu and lain.menu_iterator.iterate
-- (Specific code not provided in the input text for this part)
```

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

### Configure Lain Layout Icons in Theme

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

Sets up variables in the Awesome WM theme to specify the path to Lain layout icons and defines specific icon paths for various layouts. This allows visual representation of different window arrangements.

```lua
theme.lain_icons         = os.getenv("HOME") ..
                           "/.config/awesome/lain/icons/layout/default/"
theme.layout_termfair    = theme.lain_icons .. "termfair.png"
theme.layout_centerfair  = theme.lain_icons .. "centerfair.png"  -- termfair.center
theme.layout_cascade     = theme.lain_icons .. "cascade.png"
theme.layout_cascadetile = theme.lain_icons .. "cascadetile.png" -- cascade.tile
theme.layout_centerwork  = theme.lain_icons .. "centerwork.png"
theme.layout_centerworkh = theme.lain_icons .. "centerworkh.png" -- centerwork.horizontal
```

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

### Create Key Binding for Weather Pop-up (Lua)

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

Creates a keyboard shortcut to display the weather pop-up. This function binds a key combination (Mod1 + 'w') to a Lua function that calls `myweather.show()` with a specified timeout in seconds. Requires the `awful` library.

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

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

### Initialize tp_smapi Interface in Lua

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

Initializes the tp_smapi interface, which allows querying ThinkPad battery status. An optional API path can be provided; otherwise, a default path is used. This is the first step before using any other tp_smapi functions.

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

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

### Menu for Current Tags with lain (Lua)

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

Displays a menu containing only clients from currently visible tags, similar to `awful.menu.clients`. Accepts optional table for menu configuration.

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

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

### Dynamic Tag Management with lain (Lua)

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

Provides functions to dynamically add, rename, move, and delete tags in AwesomeWM. Use with caution when deleting tags as associated rules will be broken.

```lua
awful.key({ modkey, "Shift" }, "n", function () lain.util.add_tag(mylayout) end),
awful.key({ modkey, "Shift" }, "r", function () lain.util.rename_tag() end),
awful.key({ modkey, "Shift" }, "Left", function () lain.util.move_tag(1) end),   -- move to next tag
awful.key({ modkey, "Shift" }, "Right", function () lain.util.move_tag(-1) end), -- move to previous tag
awful.key({ modkey, "Shift" }, "d", function () lain.util.delete_tag() end)
```

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

### MOC Control Keybindings (Lua)

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

Defines keybindings to control MOC playback, including toggling play/pause, stopping, skipping to the previous track, and playing the next track. Each keybinding executes an 'os.execute' command for MOC and updates the widget.

```lua
-- MOC control
awful.key({ altkey, "Control" }, "Up",
	function ()
		os.execute("mocp -G") -- toggle
		moc.update()
	end),
awful.key({ altkey, "Control" }, "Down",
	function ()
		os.execute("mocp -s") -- stop
		moc.update()
	end),
awful.key({ altkey, "Control" }, "Left",
	function ()
		os.execute("mocp -r") -- previous
		moc.update()
	end),
awful.key({ altkey, "Control" }, "Right",
	function ()
		os.execute("mocp -f") -- next
		moc.update()
	end)
```

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

### Markup Font and Color Usage (Lua)

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

Demonstrates the usage of `markup.font` and `markup.color` functions for applying specific fonts and colors to text. These functions allow for direct control over text presentation.

```lua
markup.font(font, text)
```

```lua
markup.color(fg, bg, text)
```