+
+## Why
+
+[AwesomeWM](https://awesomewm.org/) is literally what it stands for, an awesome window manager.
+
+Its unique selling point has always been the widget system, which allows for fancy buttons, sliders, bars, dashboards and anything you can imagine. But that feature can be a curse. Most modules focus on the widget side of things which leave the actual window managing part of AwesomeWM underdeveloped compared to, for example, [xmonad](https://xmonad.org/) even though it's probably just as powerfull in that area.
+
+This project focuses on that problem - adding new layouts and modules that make use of the widget system, but primarily focus on the new window managing features.
+
+## Installation
+- clone this repo into your `~/.config/awesome` folder
+ - `git clone https://github.com/Nooo37/bling.git ~/.config/awesome/bling`
+- require the module in your `rc.lua`, and make sure it's under the beautiful module initialization
+
+```lua
+-- other imports
+
+local beautiful = require("beautiful")
+
+-- other configuration stuff here
+
+beautiful.init("some_theme.lua")
+local bling = require("bling")
+```
+
+## Contributors
+A special thanks to all our contributors...
+
+
+
+
+
+Made with [contributors-img](https://contrib.rocks).
diff --git a/docs/index.html b/docs/index.html
new file mode 100644
index 0000000..7f0cae4
--- /dev/null
+++ b/docs/index.html
@@ -0,0 +1,27 @@
+
+
+
+
+ Bling Docs
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/layouts/layout.md b/docs/layouts/layout.md
new file mode 100644
index 0000000..97c8ab6
--- /dev/null
+++ b/docs/layouts/layout.md
@@ -0,0 +1,44 @@
+## 📎 Layouts
+
+Choose layouts from the list below and add them to to your `awful.layouts` list in your `rc.lua`.
+
+Everyone of them supports multiple master clients and master width factor making them easy to use.
+
+The mstab layout uses the tab theme from the tabbed module.
+
+```Lua
+bling.layout.mstab
+bling.layout.centered
+bling.layout.vertical
+bling.layout.horizontal
+```
+
+### Theme Variables
+```lua
+-- mstab
+theme.mstab_bar_ontop = false -- whether you want to allow the bar to be ontop of clients
+theme.mstab_dont_resize_slaves = false -- whether the tabbed stack windows should be smaller than the
+ -- currently focused stack window (set it to true if you use
+ -- transparent terminals. False if you use shadows on solid ones
+theme.mstab_bar_padding = "default" -- how much padding there should be between clients and your tabbar
+ -- by default it will adjust based on your useless gaps.
+ -- If you want a custom value. Set it to the number of pixels (int)
+theme.mstab_border_radius = 0 -- border radius of the tabbar
+theme.mstab_bar_height = 40 -- height of the tabbar
+theme.mstab_tabbar_position = "top" -- position of the tabbar (mstab currently does not support left,right)
+theme.mstab_tabbar_style = "default" -- style of the tabbar ("default", "boxes" or "modern")
+ -- defaults to the tabbar_style so only change if you want a
+ -- different style for mstab and tabbed
+```
+
+### Previews
+
+#### Mstab (dynamic tabbing layout)
+
+
+*screenshot by [javacafe](https://github.com/JavaCafe01)*
+
+#### Centered
+
+
+*screenshot by [branwright](https://github.com/branwright1)*
diff --git a/docs/module/flash.md b/docs/module/flash.md
new file mode 100644
index 0000000..ed4fa42
--- /dev/null
+++ b/docs/module/flash.md
@@ -0,0 +1,33 @@
+## 🔦 Flash Focus
+
+Flash focus does an opacity animation effect on a client when it is focused.
+
+
+### Usage
+
+There are two ways in which you can use this module. You can enable it by calling the `enable()` function:
+```lua
+bling.module.flash_focus.enable()
+```
+This connects to the focus signal of a client, which means that the flash focus will activate however you focus the client.
+
+The other way is to call the function itself like this: `bling.module.flash_focus.flashfocus(someclient)`. This allows you to activate on certain keybinds like so:
+```lua
+awful.key({modkey}, "Up",
+ function()
+ awful.client.focus.bydirection("up")
+ bling.module.flash_focus.flashfocus(client.focus)
+ end, {description = "focus up", group = "client"})
+```
+
+### Theme Variables
+```lua
+theme.flash_focus_start_opacity = 0.6 -- the starting opacity
+theme.flash_focus_step = 0.01 -- the step of animation
+```
+
+### Preview
+
+
+
+*gif by [JavaCafe01](https://github.com/JavaCafe01)*
diff --git a/docs/module/swal.md b/docs/module/swal.md
new file mode 100644
index 0000000..ad40c0f
--- /dev/null
+++ b/docs/module/swal.md
@@ -0,0 +1,24 @@
+## 😋 Window Swallowing
+
+Can your window manager swallow? It probably can...
+
+### Usage
+
+To activate and deactivate window swallowing here are the following functions. If you want to activate it, just call the `start` function once in your `rc.lua`.
+```lua
+bling.module.window_swallowing.start() -- activates window swallowing
+bling.module.window_swallowing.stop() -- deactivates window swallowing
+bling.module.window_swallowing.toggle() -- toggles window swallowing
+```
+
+### Theme Variables
+```lua
+theme.dont_swallow_classname_list = {"firefox", "Gimp"} -- list of class names that should not be swallowed
+theme.dont_swallow_filter_activated = true -- whether the filter above should be active
+```
+
+### Preview
+
+
+
+*gif by [Nooo37](https://github.com/Nooo37)*
diff --git a/docs/module/tabbed.md b/docs/module/tabbed.md
new file mode 100644
index 0000000..1c82253
--- /dev/null
+++ b/docs/module/tabbed.md
@@ -0,0 +1,45 @@
+## 📑 Tabbed
+
+Tabbed implements a tab container. There are also different themes for the tabs.
+
+### Usage
+
+You should bind these functions to keys in order to use the tabbed module effectively:
+```lua
+bling.module.tabbed.pick() -- picks a client with your cursor to add to the tabbing group
+bling.module.tabbed.pop() -- removes the focused client from the tabbing group
+bling.module.tabbed.iter() -- iterates through the currently focused tabbing group
+bling.module.tabbed.pick_with_dmenu() -- picks a client with a dmenu application (defaults to rofi, other options can be set with a string parameter like "dmenu")
+```
+
+### Theme Variables
+
+```lua
+-- For tabbed only
+theme.tabbed_spawn_in_tab = false -- whether a new client should spawn into the focused tabbing container
+
+-- For tabbar in general
+theme.tabbar_ontop = false
+theme.tabbar_radius = 0 -- border radius of the tabbar
+theme.tabbar_style = "default" -- style of the tabbar ("default", "boxes" or "modern")
+theme.tabbar_font = "Sans 11" -- font of the tabbar
+theme.tabbar_size = 40 -- size of the tabbar
+theme.tabbar_position = "top" -- position of the tabbar
+theme.tabbar_bg_normal = "#000000" -- background color of the focused client on the tabbar
+theme.tabbar_fg_normal = "#ffffff" -- foreground color of the focused client on the tabbar
+theme.tabbar_bg_focus = "#1A2026" -- background color of unfocused clients on the tabbar
+theme.tabbar_fg_focus = "#ff0000" -- foreground color of unfocused clients on the tabbar
+
+-- the following variables are currently only for the "modern" tabbar style
+theme.tabbar_color_close = "#f9929b" -- chnges the color of the close button
+theme.tabbar_color_min = "#fbdf90" -- chnges the color of the minimize button
+theme.tabbar_color_float = "#ccaced" -- chnges the color of the float button
+```
+
+### Preview
+
+Modern theme:
+
+
+
+*screenshot by [javacafe](https://github.com/JavaCafe01)*
diff --git a/docs/module/twall.md b/docs/module/twall.md
new file mode 100644
index 0000000..73ef4a3
--- /dev/null
+++ b/docs/module/twall.md
@@ -0,0 +1,25 @@
+## 🏬 Tiled Wallpaper
+
+### Usage
+
+The function to set an automatically created tiled wallpaper can be called the following way (you don't need to set every option in the table):
+```lua
+awful.screen.connect_for_each_screen(function(s) -- that way the wallpaper is applied to every screen
+ bling.module.tiled_wallpaper("x", s, { -- call the actual function ("x" is the string that will be tiled)
+ fg = "#ff0000", -- define the foreground color
+ bg = "#00ffff", -- define the background color
+ offset_y = 25, -- set a y offset
+ offset_x = 25, -- set a x offset
+ font = "Hack", -- set the font (without the size)
+ font_size = 14, -- set the font size
+ padding = 100, -- set padding (default is 100)
+ zickzack = true -- rectangular pattern or criss cross
+ })
+end)
+```
+
+### Preview
+
+
+
+*screenshots by [Nooo37](https://github.com/Nooo37)*
diff --git a/docs/module/wall.md b/docs/module/wall.md
new file mode 100644
index 0000000..12a5e4d
--- /dev/null
+++ b/docs/module/wall.md
@@ -0,0 +1,127 @@
+## 🎇 Wallpaper Easy Setup
+
+This is a simple-to-use, extensible, declarative wallpaper manager.
+
+### Practical Examples
+
+```lua
+-- A default Awesome wallpaper
+bling.module.wallpaper.setup()
+
+-- A slideshow with pictures from different sources changing every 30 minutes
+bling.module.wallpaper.setup {
+ wallpaper = {"/images/my_dog.jpg", "/images/my_cat.jpg"},
+ change_timer = 1800
+}
+
+-- A random wallpaper with images from multiple folders
+bling.module.wallpaper.setup {
+ set_function = bling.module.wallpaper.setters.random
+ wallpaper = {"/path/to/a/folder", "/path/to/another/folder"},
+ change_timer = 631, -- prime numbers are better for timers
+ position = "fit",
+ background = "#424242"
+}
+
+-- wallpapers based on a schedule, like awesome-glorious-widgets dynamic wallpaper
+-- https://github.com/manilarome/awesome-glorious-widgets/tree/master/dynamic-wallpaper
+bling.module.wallpaper.setup {
+ set_function = wallpaper.setters.simple_schedule,
+ wallpaper = {
+ ["06:22:00"] = "morning-wallpaper.jpg",
+ ["12:00:00"] = "noon-wallpaper.jpg",
+ ["17:58:00"] = "night-wallpaper.jpg",
+ ["24:00:00"] = "midnight-wallpaper.jpg",
+ },
+ position = "maximized",
+}
+
+-- random wallpapers, from different folder depending on time of the day
+bling.module.wallpaper.setup {
+ set_function = bling.module.wallpaper.setters.simple_schedule,
+ wallpaper = {
+ ["09:00:00"] = "~/Pictures/safe_for_work",
+ ["18:00:00"] = "~/Pictures/personal",
+ },
+ schedule_set_function = bling.module.wallpaper.setters.random
+ position = "maximized",
+ recursive = false,
+ change_timer = 600
+}
+```
+### Details
+
+The setup function will do 2 things: call the set-function when awesome requests a wallpaper, and manage a timer to call `set_function` periodically.
+
+Its argument is a args table that is passed to ohter functions (setters and wallpaper functions), so you define everything with setup.
+
+The `set_function` is a function called every times a wallpaper is needed.
+
+The module provides some setters:
+
+* `bling.module.wallpaper.setters.awesome_wallpaper`: beautiful.theme_assets.wallpaper with defaults from beautiful.
+* `bling.module.wallpaper.setters.simple`: slideshow from the `wallpaper` argument.
+* `bling.module.wallpaper.setters.random`: same as simple but in a random way.
+* `bling.module.wallpaper.setters.simple_schedule`: takes a table of `["HH:MM:SS"] = wallpaper` arguments, where wallpaper is the `wallpaper` argument used by `schedule_set_function`.
+
+A wallpaper is one of the following elements:
+
+* a color
+* an image
+* a folder containing images
+* a function that sets a wallpaper
+* everything gears.wallpaper functions can manage (cairo surface, cairo pattern string)
+* a list containing any of the elements above
+
+```lua
+-- This is a valid wallpaper definition
+bling.module.wallpaper.setup {
+ wallpaper = { -- a list
+ "black", "#112233", -- colors
+ "wall1.jpg", "wall2.png", -- files
+ "/path/to/wallpapers", -- folders
+ -- cairo patterns
+ "radial:600,50,100:105,550,900:0,#2200ff:0.5,#00ff00:1,#101010",
+ -- or functions that set a wallpaper
+ function(args) bling.module.tiled_wallpaper("\\o/", args.screen) end,
+ bling.module.wallpaper.setters.awesome_wallpaper,
+ },
+ change_timer = 10,
+}
+```
+The provided setters `simple` and `random` will use 2 internal functions that you can use to write your own setter:
+
+* `bling.module.wallpaper.prepare_list`: return a list of wallpapers directly usable by `apply` (for now, it just explores folders)
+* `bling.module.wallpaper.apply`: a wrapper for gears.wallpaper functions, using the args table of setup
+
+Here are the defaults:
+
+```lua
+-- Default parameters
+bling.module.wallpaper.setup {
+ screen = nil, -- the screen to apply the wallpaper, as seen in gears.wallpaper functions
+ change_timer = nil, -- the timer in seconds. If set, call the set_function every change_timer seconds
+ set_function = nil, -- the setter function
+
+ -- parameters used by bling.module.wallpaper.prepare_list
+ wallpaper = nil, -- the wallpaper object, see simple or simple_schedule documentation
+ image_formats = {"jpg", "jpeg", "png", "bmp"}, -- when searching in folder, consider these files only
+ recursive = true, -- when searching in folder, search also in subfolders
+
+ -- parameters used by bling.module.wallpaper.apply
+ position = nil, -- use a function of gears.wallpaper when applicable ("centered", "fit", "maximized", "tiled")
+ background = beautiful.bg_normal or "black", -- see gears.wallpaper functions
+ ignore_aspect = false, -- see gears.wallpaper.maximized
+ offset = {x = 0, y = 0}, -- see gears.wallpaper functions
+ scale = 1, -- see gears.wallpaper.centered
+
+ -- parameters that only apply to bling.module.wallpaper.setter.awesome (as a setter or as a wallpaper function)
+ colors = { -- see beautiful.theme_assets.wallpaper
+ bg = beautiful.bg_color, -- the actual default is this color but darkened or lightned
+ fg = beautiful.fg_color,
+ alt_fg = beautiful.fg_focus
+ }
+}
+```
+
+Check documentation in [module/wallpaper.lua](module/wallpaper.lua) for more details.
diff --git a/docs/signals/pctl.md b/docs/signals/pctl.md
new file mode 100644
index 0000000..b06d69c
--- /dev/null
+++ b/docs/signals/pctl.md
@@ -0,0 +1,88 @@
+## 🎵 Playerctl
+
+This is a signal module in which you can connect to certain bling signals to grab playerctl info. Currently, this is what it supports:
+
+- Song title and artist
+- Album art (the path this module downloaded the art to)
+- If playing or not
+- Position
+- Song length
+
+This module relies on `playerctl` and `curl`. If you have this module disabled, you won't need those programs. With this module, you can create a widget like below without worrying about the backend.
+
+
+
+*screenshot by [javacafe](https://github.com/JavaCafe01)*
+
+### Usage
+
+To enable: `bling.signal.playerctl.enable()`
+
+Here are the signals available:
+
+```lua
+-- bling::playerctl::status -- first line is the signal
+-- playing (boolean) -- indented lines are function parameters
+-- bling::playerctl::title_artist_album
+-- title (string)
+-- artist (string)
+-- album_path (string)
+-- bling::playerctl::position
+-- interval_sec (number)
+-- length_sec (number)
+```
+
+### Example Implementation
+
+Lets say we have an imagebox. If I wanted to set the imagebox to show the album art, all I have to do is this:
+```lua
+local art = wibox.widget {
+ image = "default_image.png",
+ resize = true,
+ forced_height = dpi(80),
+ forced_width = dpi(80),
+ widget = wibox.widget.imagebox
+}
+
+local title_widget = wibox.widget {
+ markup = 'Nothing Playing',
+ align = 'center',
+ valign = 'center',
+ widget = wibox.widget.textbox
+}
+
+local artist_widget = wibox.widget {
+ markup = 'Nothing Playing',
+ align = 'center',
+ valign = 'center',
+ widget = wibox.widget.textbox
+}
+
+-- Get Song Info
+awesome.connect_signal("bling::playerctl::title_artist_album",
+ function(title, artist, art_path)
+ -- Set art widget
+ art:set_image(gears.surface.load_uncached(art_path))
+
+ -- Set title and artist widgets
+ title_widget:set_markup_silently(title)
+ artist_widget:set_markup_silently(artist)
+end)
+```
+Thats all! You don't even have to worry about updating the widgets, the signals will handle that for you.
+
+Here's another example in which you get a notification with the album art, title, and artist whenever the song changes.
+
+```lua
+local naughty = require("naughty")
+
+awesome.connect_signal("bling::playerctl::title_artist_album",
+ function(title, artist, art_path)
+ naughty.notify({title = title, text = artist, image = art_path})
+end)
+```
+
+### Theme Variables
+```lua
+theme.playerctl_position_update_interval = 1 -- the update interval for fetching the position from playerctl
+```
diff --git a/docs/theme.md b/docs/theme.md
new file mode 100644
index 0000000..5814a2e
--- /dev/null
+++ b/docs/theme.md
@@ -0,0 +1,54 @@
+```lua
+--[[ Bling theme variables template
+This file has all theme variables of the bling module.
+Every variable has a small comment on what it does.
+You might just want to copy that whole part into your theme.lua and start adjusting from there.
+--]]
+
+
+-- window swallowing
+theme.dont_swallow_classname_list = {"firefox", "Gimp"} -- list of class names that should not be swallowed
+theme.dont_swallow_filter_activated = true -- whether the filter above should be active
+
+-- flash focus
+theme.flash_focus_start_opacity = 0.6 -- the starting opacity
+theme.flash_focus_step = 0.01 -- the step of animation
+
+-- playerctl signal
+theme.playerctl_position_update_interval = 1 -- the update interval for fetching the position from playerctl
+
+-- tabbed
+theme.tabbed_spawn_in_tab = false -- whether a new client should spawn into the focused tabbing container
+
+-- tabbar general
+theme.tabbar_ontop = false
+theme.tabbar_radius = 0 -- border radius of the tabbar
+theme.tabbar_style = "default" -- style of the tabbar ("default", "boxes" or "modern")
+theme.tabbar_font = "Sans 11" -- font of the tabbar
+theme.tabbar_size = 40 -- size of the tabbar
+theme.tabbar_position = "top" -- position of the tabbar
+theme.tabbar_bg_normal = "#000000" -- background color of the focused client on the tabbar
+theme.tabbar_fg_normal = "#ffffff" -- foreground color of the focused client on the tabbar
+theme.tabbar_bg_focus = "#1A2026" -- background color of unfocused clients on the tabbar
+theme.tabbar_fg_focus = "#ff0000" -- foreground color of unfocused clients on the tabbar
+
+-- mstab
+theme.mstab_bar_ontop = false -- whether you want to allow the bar to be ontop of clients
+theme.mstab_dont_resize_slaves = false -- whether the tabbed stack windows should be smaller than the
+ -- currently focused stack window (set it to true if you use
+ -- transparent terminals. False if you use shadows on solid ones
+theme.mstab_bar_padding = "default" -- how much padding there should be between clients and your tabbar
+ -- by default it will adjust based on your useless gaps.
+ -- If you want a custom value. Set it to the number of pixels (int)
+theme.mstab_border_radius = 0 -- border radius of the tabbar
+theme.mstab_bar_height = 40 -- height of the tabbar
+theme.mstab_tabbar_position = "top" -- position of the tabbar (mstab currently does not support left,right)
+theme.mstab_tabbar_style = "default" -- style of the tabbar ("default", "boxes" or "modern")
+ -- defaults to the tabbar_style so only change if you want a
+ -- different style for mstab and tabbed
+
+-- the following variables are currently only for the "modern" tabbar style
+theme.tabbar_color_close = "#f9929b" -- chnges the color of the close button
+theme.tabbar_color_min = "#fbdf90" -- chnges the color of the minimize button
+theme.tabbar_color_float = "#ccaced" -- chnges the color of the float button
+```
+
+*screenshot by [javacafe](https://github.com/JavaCafe01)*
diff --git a/docs/module/twall.md b/docs/module/twall.md
new file mode 100644
index 0000000..73ef4a3
--- /dev/null
+++ b/docs/module/twall.md
@@ -0,0 +1,25 @@
+## 🏬 Tiled Wallpaper
+
+### Usage
+
+The function to set an automatically created tiled wallpaper can be called the following way (you don't need to set every option in the table):
+```lua
+awful.screen.connect_for_each_screen(function(s) -- that way the wallpaper is applied to every screen
+ bling.module.tiled_wallpaper("x", s, { -- call the actual function ("x" is the string that will be tiled)
+ fg = "#ff0000", -- define the foreground color
+ bg = "#00ffff", -- define the background color
+ offset_y = 25, -- set a y offset
+ offset_x = 25, -- set a x offset
+ font = "Hack", -- set the font (without the size)
+ font_size = 14, -- set the font size
+ padding = 100, -- set padding (default is 100)
+ zickzack = true -- rectangular pattern or criss cross
+ })
+end)
+```
+
+### Preview
+
+
+
+*screenshots by [Nooo37](https://github.com/Nooo37)*
diff --git a/docs/module/wall.md b/docs/module/wall.md
new file mode 100644
index 0000000..12a5e4d
--- /dev/null
+++ b/docs/module/wall.md
@@ -0,0 +1,127 @@
+## 🎇 Wallpaper Easy Setup
+
+This is a simple-to-use, extensible, declarative wallpaper manager.
+
+### Practical Examples
+
+```lua
+-- A default Awesome wallpaper
+bling.module.wallpaper.setup()
+
+-- A slideshow with pictures from different sources changing every 30 minutes
+bling.module.wallpaper.setup {
+ wallpaper = {"/images/my_dog.jpg", "/images/my_cat.jpg"},
+ change_timer = 1800
+}
+
+-- A random wallpaper with images from multiple folders
+bling.module.wallpaper.setup {
+ set_function = bling.module.wallpaper.setters.random
+ wallpaper = {"/path/to/a/folder", "/path/to/another/folder"},
+ change_timer = 631, -- prime numbers are better for timers
+ position = "fit",
+ background = "#424242"
+}
+
+-- wallpapers based on a schedule, like awesome-glorious-widgets dynamic wallpaper
+-- https://github.com/manilarome/awesome-glorious-widgets/tree/master/dynamic-wallpaper
+bling.module.wallpaper.setup {
+ set_function = wallpaper.setters.simple_schedule,
+ wallpaper = {
+ ["06:22:00"] = "morning-wallpaper.jpg",
+ ["12:00:00"] = "noon-wallpaper.jpg",
+ ["17:58:00"] = "night-wallpaper.jpg",
+ ["24:00:00"] = "midnight-wallpaper.jpg",
+ },
+ position = "maximized",
+}
+
+-- random wallpapers, from different folder depending on time of the day
+bling.module.wallpaper.setup {
+ set_function = bling.module.wallpaper.setters.simple_schedule,
+ wallpaper = {
+ ["09:00:00"] = "~/Pictures/safe_for_work",
+ ["18:00:00"] = "~/Pictures/personal",
+ },
+ schedule_set_function = bling.module.wallpaper.setters.random
+ position = "maximized",
+ recursive = false,
+ change_timer = 600
+}
+```
+### Details
+
+The setup function will do 2 things: call the set-function when awesome requests a wallpaper, and manage a timer to call `set_function` periodically.
+
+Its argument is a args table that is passed to ohter functions (setters and wallpaper functions), so you define everything with setup.
+
+The `set_function` is a function called every times a wallpaper is needed.
+
+The module provides some setters:
+
+* `bling.module.wallpaper.setters.awesome_wallpaper`: beautiful.theme_assets.wallpaper with defaults from beautiful.
+* `bling.module.wallpaper.setters.simple`: slideshow from the `wallpaper` argument.
+* `bling.module.wallpaper.setters.random`: same as simple but in a random way.
+* `bling.module.wallpaper.setters.simple_schedule`: takes a table of `["HH:MM:SS"] = wallpaper` arguments, where wallpaper is the `wallpaper` argument used by `schedule_set_function`.
+
+A wallpaper is one of the following elements:
+
+* a color
+* an image
+* a folder containing images
+* a function that sets a wallpaper
+* everything gears.wallpaper functions can manage (cairo surface, cairo pattern string)
+* a list containing any of the elements above
+
+```lua
+-- This is a valid wallpaper definition
+bling.module.wallpaper.setup {
+ wallpaper = { -- a list
+ "black", "#112233", -- colors
+ "wall1.jpg", "wall2.png", -- files
+ "/path/to/wallpapers", -- folders
+ -- cairo patterns
+ "radial:600,50,100:105,550,900:0,#2200ff:0.5,#00ff00:1,#101010",
+ -- or functions that set a wallpaper
+ function(args) bling.module.tiled_wallpaper("\\o/", args.screen) end,
+ bling.module.wallpaper.setters.awesome_wallpaper,
+ },
+ change_timer = 10,
+}
+```
+The provided setters `simple` and `random` will use 2 internal functions that you can use to write your own setter:
+
+* `bling.module.wallpaper.prepare_list`: return a list of wallpapers directly usable by `apply` (for now, it just explores folders)
+* `bling.module.wallpaper.apply`: a wrapper for gears.wallpaper functions, using the args table of setup
+
+Here are the defaults:
+
+```lua
+-- Default parameters
+bling.module.wallpaper.setup {
+ screen = nil, -- the screen to apply the wallpaper, as seen in gears.wallpaper functions
+ change_timer = nil, -- the timer in seconds. If set, call the set_function every change_timer seconds
+ set_function = nil, -- the setter function
+
+ -- parameters used by bling.module.wallpaper.prepare_list
+ wallpaper = nil, -- the wallpaper object, see simple or simple_schedule documentation
+ image_formats = {"jpg", "jpeg", "png", "bmp"}, -- when searching in folder, consider these files only
+ recursive = true, -- when searching in folder, search also in subfolders
+
+ -- parameters used by bling.module.wallpaper.apply
+ position = nil, -- use a function of gears.wallpaper when applicable ("centered", "fit", "maximized", "tiled")
+ background = beautiful.bg_normal or "black", -- see gears.wallpaper functions
+ ignore_aspect = false, -- see gears.wallpaper.maximized
+ offset = {x = 0, y = 0}, -- see gears.wallpaper functions
+ scale = 1, -- see gears.wallpaper.centered
+
+ -- parameters that only apply to bling.module.wallpaper.setter.awesome (as a setter or as a wallpaper function)
+ colors = { -- see beautiful.theme_assets.wallpaper
+ bg = beautiful.bg_color, -- the actual default is this color but darkened or lightned
+ fg = beautiful.fg_color,
+ alt_fg = beautiful.fg_focus
+ }
+}
+```
+
+Check documentation in [module/wallpaper.lua](module/wallpaper.lua) for more details.
diff --git a/docs/signals/pctl.md b/docs/signals/pctl.md
new file mode 100644
index 0000000..b06d69c
--- /dev/null
+++ b/docs/signals/pctl.md
@@ -0,0 +1,88 @@
+## 🎵 Playerctl
+
+This is a signal module in which you can connect to certain bling signals to grab playerctl info. Currently, this is what it supports:
+
+- Song title and artist
+- Album art (the path this module downloaded the art to)
+- If playing or not
+- Position
+- Song length
+
+This module relies on `playerctl` and `curl`. If you have this module disabled, you won't need those programs. With this module, you can create a widget like below without worrying about the backend.
+
+
+
+*screenshot by [javacafe](https://github.com/JavaCafe01)*
+
+### Usage
+
+To enable: `bling.signal.playerctl.enable()`
+
+Here are the signals available:
+
+```lua
+-- bling::playerctl::status -- first line is the signal
+-- playing (boolean) -- indented lines are function parameters
+-- bling::playerctl::title_artist_album
+-- title (string)
+-- artist (string)
+-- album_path (string)
+-- bling::playerctl::position
+-- interval_sec (number)
+-- length_sec (number)
+```
+
+### Example Implementation
+
+Lets say we have an imagebox. If I wanted to set the imagebox to show the album art, all I have to do is this:
+```lua
+local art = wibox.widget {
+ image = "default_image.png",
+ resize = true,
+ forced_height = dpi(80),
+ forced_width = dpi(80),
+ widget = wibox.widget.imagebox
+}
+
+local title_widget = wibox.widget {
+ markup = 'Nothing Playing',
+ align = 'center',
+ valign = 'center',
+ widget = wibox.widget.textbox
+}
+
+local artist_widget = wibox.widget {
+ markup = 'Nothing Playing',
+ align = 'center',
+ valign = 'center',
+ widget = wibox.widget.textbox
+}
+
+-- Get Song Info
+awesome.connect_signal("bling::playerctl::title_artist_album",
+ function(title, artist, art_path)
+ -- Set art widget
+ art:set_image(gears.surface.load_uncached(art_path))
+
+ -- Set title and artist widgets
+ title_widget:set_markup_silently(title)
+ artist_widget:set_markup_silently(artist)
+end)
+```
+Thats all! You don't even have to worry about updating the widgets, the signals will handle that for you.
+
+Here's another example in which you get a notification with the album art, title, and artist whenever the song changes.
+
+```lua
+local naughty = require("naughty")
+
+awesome.connect_signal("bling::playerctl::title_artist_album",
+ function(title, artist, art_path)
+ naughty.notify({title = title, text = artist, image = art_path})
+end)
+```
+
+### Theme Variables
+```lua
+theme.playerctl_position_update_interval = 1 -- the update interval for fetching the position from playerctl
+```
diff --git a/docs/theme.md b/docs/theme.md
new file mode 100644
index 0000000..5814a2e
--- /dev/null
+++ b/docs/theme.md
@@ -0,0 +1,54 @@
+```lua
+--[[ Bling theme variables template
+This file has all theme variables of the bling module.
+Every variable has a small comment on what it does.
+You might just want to copy that whole part into your theme.lua and start adjusting from there.
+--]]
+
+
+-- window swallowing
+theme.dont_swallow_classname_list = {"firefox", "Gimp"} -- list of class names that should not be swallowed
+theme.dont_swallow_filter_activated = true -- whether the filter above should be active
+
+-- flash focus
+theme.flash_focus_start_opacity = 0.6 -- the starting opacity
+theme.flash_focus_step = 0.01 -- the step of animation
+
+-- playerctl signal
+theme.playerctl_position_update_interval = 1 -- the update interval for fetching the position from playerctl
+
+-- tabbed
+theme.tabbed_spawn_in_tab = false -- whether a new client should spawn into the focused tabbing container
+
+-- tabbar general
+theme.tabbar_ontop = false
+theme.tabbar_radius = 0 -- border radius of the tabbar
+theme.tabbar_style = "default" -- style of the tabbar ("default", "boxes" or "modern")
+theme.tabbar_font = "Sans 11" -- font of the tabbar
+theme.tabbar_size = 40 -- size of the tabbar
+theme.tabbar_position = "top" -- position of the tabbar
+theme.tabbar_bg_normal = "#000000" -- background color of the focused client on the tabbar
+theme.tabbar_fg_normal = "#ffffff" -- foreground color of the focused client on the tabbar
+theme.tabbar_bg_focus = "#1A2026" -- background color of unfocused clients on the tabbar
+theme.tabbar_fg_focus = "#ff0000" -- foreground color of unfocused clients on the tabbar
+
+-- mstab
+theme.mstab_bar_ontop = false -- whether you want to allow the bar to be ontop of clients
+theme.mstab_dont_resize_slaves = false -- whether the tabbed stack windows should be smaller than the
+ -- currently focused stack window (set it to true if you use
+ -- transparent terminals. False if you use shadows on solid ones
+theme.mstab_bar_padding = "default" -- how much padding there should be between clients and your tabbar
+ -- by default it will adjust based on your useless gaps.
+ -- If you want a custom value. Set it to the number of pixels (int)
+theme.mstab_border_radius = 0 -- border radius of the tabbar
+theme.mstab_bar_height = 40 -- height of the tabbar
+theme.mstab_tabbar_position = "top" -- position of the tabbar (mstab currently does not support left,right)
+theme.mstab_tabbar_style = "default" -- style of the tabbar ("default", "boxes" or "modern")
+ -- defaults to the tabbar_style so only change if you want a
+ -- different style for mstab and tabbed
+
+-- the following variables are currently only for the "modern" tabbar style
+theme.tabbar_color_close = "#f9929b" -- chnges the color of the close button
+theme.tabbar_color_min = "#fbdf90" -- chnges the color of the minimize button
+theme.tabbar_color_float = "#ccaced" -- chnges the color of the float button
+```