Merge pull request #17 from Grumph/master

refactored helpers path, added wallpaper module

README.md

@@ -51,6 +51,133 @@ awful.screen.connect_for_each_screen(function(s)  -- that way the wallpaper is a
 end)
 ```
 
+##### 🎇 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.
+
+
 ##### 🔦 Flash Focus
 
 There are two ways you can use this module. You can just enable it by calling the `enable()` function:
@@ -115,6 +242,7 @@ gif by [javacafe](https://github.com/JavaCafe01)
 gif by me :)
 
 ## TODO
+- [ ] Add external sources management for the wallpaper module (URLs, RSS feeds, NASA picture of the day, ...)
 - [ ] Scratchpad module
 - [x] Some more documentation on the tabbed module
 - [x] Add a cool alternative tabbar style  

helpers/client.lua

@@ -0,0 +1,34 @@
+local awful = require("awful")
+
+local _client = {}
+
+--- Turn off passed client
+-- Remove current tag from window's tags
+--
+-- @param c a client
+function _client.turn_off(c)
+    local current_tag = awful.tag.selected(c.screen)
+    local ctags = {}
+    for k, tag in pairs(c:tags()) do
+        if tag ~= current_tag then table.insert(ctags, tag) end
+    end
+    c:tags(ctags)
+end
+
+--- Turn on passed client (add current tag to window's tags)
+--
+-- @param c A client
+function _client.turn_on(c)
+    local current_tag = awful.tag.selected(c.screen)
+    ctags = {current_tag}
+    for k, tag in pairs(c:tags()) do
+        if tag ~= current_tag then table.insert(ctags, tag) end
+    end
+    c:tags(ctags)
+    c:raise()
+    client.focus = c
+end
+
+
+
+return _client

helpers/color.lua

@@ -0,0 +1,59 @@
+
+
+local _color = {}
+
+
+
+--- Try to guess if a color is dark or light.
+--
+-- @string color The color with hexadecimal HTML format `"#RRGGBB"`.
+-- @treturn bool `true` if the color is dark, `false` if it is light.
+function _color.is_dark(color)
+    -- Try to determine if the color is dark or light
+    local numeric_value = 0;
+    for s in color:gmatch("[a-fA-F0-9][a-fA-F0-9]") do
+        numeric_value = numeric_value + tonumber("0x"..s);
+    end
+    return (numeric_value < 383)
+end
+
+
+--- Lighten a color.
+--
+-- @string color The color to lighten with hexadecimal HTML format `"#RRGGBB"`.
+-- @int[opt=26] amount How much light from 0 to 255. Default is around 10%.
+-- @treturn string The lighter color
+function _color.lighten(color, amount)
+    amount = amount or 26
+    local c = {
+        r = tonumber("0x"..color:sub(2,3)),
+        g = tonumber("0x"..color:sub(4,5)),
+        b = tonumber("0x"..color:sub(6,7)),
+    }
+
+    c.r = c.r + amount
+    c.r = c.r < 0 and 0 or c.r
+    c.r = c.r > 255 and 255 or c.r
+    c.g = c.g + amount
+    c.g = c.g < 0 and 0 or c.g
+    c.g = c.g > 255 and 255 or c.g
+    c.b = c.b + amount
+    c.b = c.b < 0 and 0 or c.b
+    c.b = c.b > 255 and 255 or c.b
+
+    return string.format('#%02x%02x%02x', c.r, c.g, c.b)
+end
+
+--- Darken a color.
+--
+-- @string color The color to darken with hexadecimal HTML format `"#RRGGBB"`.
+-- @int[opt=26] amount How much dark from 0 to 255. Default is around 10%.
+-- @treturn string The darker color
+function _color.darken(color, amount)
+    amount = amount or 26
+    return _color.lighten(color, -amount)
+end
+
+
+
+return _color

helpers/filesystem.lua

@@ -0,0 +1,39 @@
+local Gio = require("lgi").Gio
+
+local _filesystem = {}
+
+--- Get a list of files from a given directory.
+-- @string path The directory to search.
+-- @tparam[opt] table exts Specific extensions to limit the search to. eg:`{ "jpg", "png" }`
+--   If ommited, all files are considered.
+-- @bool[opt=false] recursive List files from subdirectories
+-- @staticfct bling.helpers.filesystem.get_random_file_from_dir
+function _filesystem.list_directory_files(path, exts, recursive)
+    recursive = recursive or false
+    local files, valid_exts = {}, {}
+
+    -- Transforms { "jpg", ... } into { [jpg] = #, ... }
+    if exts then for i, j in ipairs(exts) do valid_exts[j:lower()] = i end end
+
+    -- Build a table of files from the path with the required extensions
+    local file_list = Gio.File.new_for_path(path):enumerate_children("standard::*", 0)
+    if file_list then
+        for file in function() return file_list:next_file() end do
+            local file_type = file:get_file_type()
+            if file_type == "REGULAR" then
+                local file_name = file:get_display_name()
+                if not exts or valid_exts[file_name:lower():match(".+%.(.*)$") or ""] then
+                    table.insert(files, file_name)
+                end
+            elseif recursive and file_type == "DIRECTORY" then
+                local file_name = file:get_display_name()
+                files = gears.table.join(files, list_directory_files(file_name, exts, recursive))
+            end
+        end
+    end
+
+    return files
+end
+
+
+return _filesystem

helpers/init.lua

@@ -0,0 +1,7 @@
+return {
+    client = require(... .. ".client"),
+    color = require(... .. ".color"),
+    filesystem = require(... .. ".filesystem"),
+    shape = require(... .. ".shape"),
+    time = require(... .. ".time")
+}

helpers/shape.lua

@@ -0,0 +1,23 @@
+local gears = require("gears")
+
+shape = {}
+
+-- Create rounded rectangle shape (in one line)
+
+function shape.rrect(radius)
+    return function(cr, width, height)
+        gears.shape.rounded_rect(cr, width, height, radius)
+    end
+end
+
+-- Create partially rounded rect
+
+function shape.prrect(radius, tl, tr, br, bl)
+    return function(cr, width, height)
+        gears.shape.partially_rounded_rect(cr, width, height, tl, tr, br, bl,
+                                           radius)
+    end
+end
+
+
+return shape

helpers/time.lua

@@ -0,0 +1,29 @@
+
+
+local time = {}
+
+
+--- Parse a time string to seconds (from midnight)
+--
+-- @string time The time (`HH:MM:SS`)
+-- @treturn int The number of seconds since 00:00:00
+function time.hhmmss_to_seconds(time)
+    hour_sec = tonumber(string.sub(time, 1, 2)) * 3600
+    min_sec = tonumber(string.sub(time, 4, 5)) * 60
+    get_sec = tonumber(string.sub(time, 7, 8))
+    return (hour_sec + min_sec + get_sec)
+end
+
+
+--- Get time difference in seconds.
+--
+-- @tparam string base The time to compare from (`HH:MM:SS`).
+-- @tparam string base The time to compare to (`HH:MM:SS`).
+-- @treturn int Number of seconds between the two times.
+function time.time_diff(base, compare)
+    local diff = time.hhmmss_to_seconds(base) - time.hhmmss_to_seconds(compare)
+    return diff
+end
+
+
+return time

init.lua

@@ -7,5 +7,6 @@
 return {
     layout = require(... .. ".layout"),
     module = require(... .. ".module"),
+    helpers = require(... .. ".helpers"),
 }
 

module/helpers.lua

@@ -1,45 +0,0 @@
-local awful = require("awful")
-local gears = require("gears")
-
-local helpers = {}
-
--- Turn off passed client (remove current tag from window's tags)
-helpers.turn_off = function(c)
-    local current_tag = awful.tag.selected(c.screen)
-    local ctags = {}
-    for k, tag in pairs(c:tags()) do
-        if tag ~= current_tag then table.insert(ctags, tag) end
-    end
-    c:tags(ctags)
-end
-
--- Turn on passed client
-helpers.turn_on = function(c)
-    local current_tag = awful.tag.selected(c.screen)
-    ctags = {current_tag}
-    for k, tag in pairs(c:tags()) do
-        if tag ~= current_tag then table.insert(ctags, tag) end
-    end
-    c:tags(ctags)
-    c:raise()
-    client.focus = c
-end
-
--- Create rounded rectangle shape (in one line)
-
-helpers.rrect = function(radius)
-    return function(cr, width, height)
-        gears.shape.rounded_rect(cr, width, height, radius)
-    end
-end
-
--- Create partially rounded rect
-
-helpers.prrect = function(radius, tl, tr, br, bl)
-    return function(cr, width, height)
-        gears.shape.partially_rounded_rect(cr, width, height, tl, tr, br, bl,
-                                           radius)
-    end
-end
-
-return helpers

module/init.lua

@@ -1,6 +1,7 @@
 return {
     window_swallowing = require(... .. ".window_swallowing"),
     tiled_wallpaper = require(... .. ".tiled_wallpaper"),
+    wallpaper = require(... .. ".wallpaper"),
     flash_focus = require(... .. ".flash_focus"),
     tabbed = require(... .. ".tabbed")
 }

module/tabbed.lua

@@ -14,7 +14,7 @@ local awful = require("awful")
 local wibox = require("wibox")
 local gears = require("gears")
 local beautiful = require("beautiful")
-local helpers = require(tostring(...):match(".*bling.module") .. ".helpers")
+local helpers = require(tostring(...):match(".*bling") .. ".helpers")
 
 local bar_style = beautiful.tabbar_style or "default"
 local bar = require(tostring(...):match(".*bling") .. ".widget.tabbar." ..
@@ -147,9 +147,9 @@ tabbed.switch_to = function(tabobj, new_idx)
     tabobj.focused_idx = new_idx
     for idx, c in ipairs(tabobj.clients) do
         if idx ~= new_idx then
-            helpers.turn_off(c)
+            helpers.client.turn_off(c)
         else
-            helpers.turn_on(c)
+            helpers.client.turn_on(c)
             c:raise()
             if old_focused_c and old_focused_c.valid then
                 c:swap(old_focused_c)

module/wallpaper.lua

@@ -0,0 +1,293 @@
+---------------------------------------------------------------------------
+-- High-level declarative function for setting your wallpaper.
+--
+--
+-- An easy way to setup a complex wallpaper with slideshow, random, schedule, extensibility.
+--
+-- @usage
+--   local wallpaper = require("wallpaper")
+--   -- A silly example
+--   wallpaper.setup {                             -- I want a wallpaper
+--       change_timer = 500,                       -- changing every 5 minutes
+--       set_function = wallpaper.setters.random,  -- in a random way
+--       wallpaper = {"#abcdef",
+--                    "~/Pictures",
+--                    wallpaper.setters.awesome},  -- from this list (a color, a directory with pictures and the Awesome wallpaper)
+--       recursive = false,                        -- do not read subfolders of "~/Pictures"
+--       position = "centered",                    -- center it on the screen (for pictures)
+--       scale = 2,                                -- 2 time bigger (for pictures)
+--   }
+--
+-- @author Grumph
+-- @copyright 2021 Grumph
+--
+---------------------------------------------------------------------------
+
+
+local beautiful = require("beautiful")
+local gears = require("gears")
+local helpers = require(tostring(...):match(".*bling") .. ".helpers")
+
+local setters = {}
+
+--- Apply a wallpaper.
+--
+-- This function is a helper that will apply a wallpaper_object,
+-- either using gears.wallpaper.set or gears.wallpaper.* higher level functions when applicable.
+-- @param wallpaper_object A wallpaper object, either
+--   a `pattern` (see `gears.wallpaper.set`)
+--   a `surf` (see `gears.wallpaper.centered`)
+--   a function that actually sets the wallpaper.
+-- @tparam table args The argument table containing any of the arguments below.
+-- @int[opt=nil] args.screen The screen to use (as used in `gears.wallpaper` functions)
+-- @string[opt=nil or "centered"] args.position The `gears.wallpaper` position function to use.
+--   Must be set when wallpaper is a file.
+--   It can be `"centered"`, `"fit"`, `"tiled"` or `"maximized"`.
+-- @string[opt=beautiful.bg_normal or "black"] args.background See `gears.wallpaper`.
+-- @bool[opt=false] args.ignore_aspect See `gears.wallpaper`.
+-- @tparam[opt={x=0,y=0}] table args.offset See `gears.wallpaper`.
+-- @int[opt=1] args.scale See `gears.wallpaper`.
+function apply(wallpaper_object, args)
+    args.background = args.background or beautiful.bg_normal or "black"
+    args.ignore_aspect = args.ignore_aspect or false  -- false = keep aspect ratio
+    args.offset = args.offset or {x = 0, y = 0}
+    args.scale = args.scale or 1
+    local positions = {
+        ["centered"] = function() gears.wallpaper.centered(wallpaper_object, args.screen, args.background, args.scale) end,
+        ["tiled"] = function() gears.wallpaper.tiled(wallpaper_object, args.screen, args.offset) end,
+        ["maximized"] = function() gears.wallpaper.maximized(wallpaper_object, args.screen, args.ignore_aspect, args.offset) end,
+        ["fit"] = function() gears.wallpaper.fit(wallpaper_object, args.screen, args.background) end,
+    }
+    if type(wallpaper_object) == "string" and gears.filesystem.file_readable(wallpaper_object) then
+        -- path of an image file, we use a position function
+        local p = args.position or "centered"
+        positions[p]()
+    elseif type(wallpaper_object) == "function" then
+        -- function
+        wallpaper_object(args)
+    elseif (not gears.color.ensure_pango_color(wallpaper_object, nil)) and args.position then
+        -- if the user sets a position function, wallpaper_object should be a cairo surface
+        positions[args.position]()
+    else
+        gears.wallpaper.set(wallpaper_object)
+    end
+end
+
+--- Converts `args.wallpaper` to a list of `wallpaper_objects` readable by `apply` function).
+--
+-- @tparam table args The argument table containing the argument below.
+-- @param[opt=`beautiful.wallpaper_path` or `"black"`] args.wallpaper A wallpaper object.
+--   It can be a color or a cairo pattern (what `gears.wallpaper.set` understands),
+--   a cairo suface (set with gears.wallpaper.set if `args.position` is nil, or with
+--   `gears.wallpaper` position functions, see `args.position`),
+--   a function similar to args.set_function that will effectively set a wallpaper (usually
+--   with `gears.wallpaper` functions),
+--   a path to a file,
+--   path to a directory containing images,
+--   or a list with any of the previous choices.
+-- @tparam[opt=`{"jpg", "jpeg", "png", "bmp"}`] table args.image_formats A list of
+--   file extensions to filter when `args.wallpaper` is a directory.
+-- @bool[opt=true] args.recursive Either to recurse or not when `args.wallpaper` is a directory.
+-- @treturn table A list of `wallpaper_objects` (what `apply` can read).
+-- @see apply
+function prepare_list(args)
+    args.image_formats = args.image_formats or {"jpg", "jpeg", "png", "bmp"}
+    args.recursive = args.recursive or true
+
+    local wallpapers = (args.wallpaper
+                        or beautiful.wallpaper_path
+                        or "black")
+    local res = {}
+    if type(wallpapers) ~= "table" then
+        wallpapers = {wallpapers}
+    end
+    for _, w in ipairs(wallpapers) do
+        -- w is either:
+        --  - a directory path (string)
+        --  - an image path or a color (string)
+        --  - a cairo surface or a cairo pattern
+        --  - a function for setting the wallpaper
+        if type(w) == "string" and gears.filesystem.dir_readable(w) then
+            local file_list = helpers.filesystem.list_directory_files(w, args.image_formats, args.recursive)
+            for _, f in ipairs(file_list) do
+                res[#res + 1] = w .. "/" .. f
+            end
+        else
+            res[#res + 1] = w
+        end
+    end
+    return res
+end
+
+local simple_index = 0
+---  Set the next wallpaper in a list.
+--
+-- @tparam table args See `prepare_list` and `apply` arguments
+-- @see apply
+-- @see prepare_list
+function setters.simple(args)
+    local wallpapers = prepare_list(args)
+    simple_index = (simple_index % #wallpapers) + 1
+    apply(wallpapers[simple_index], args)
+end
+
+--- Set a random wallpaper from a list.
+--
+-- @tparam table args See `prepare_list` and `apply` arguments
+-- @see apply
+-- @see prepare_list
+function setters.random(args)
+    local wallpapers = prepare_list(args)
+    apply(wallpapers[math.random(#wallpapers)], args)
+end
+
+
+local simple_schedule_object = nil
+--- A schedule setter.
+--
+-- This simple schedule setter was freely inspired by [dynamic-wallpaper](https://github.com/manilarome/awesome-glorious-widgets/blob/master/dynamic-wallpaper/init.lua).
+-- @tparam table args The argument table containing any of the arguments below.
+-- @tparam table args.wallpaper The schedule table, with the form
+--     {
+--      ["HH:MM:SS"] = wallpaper,
+--      ["HH:MM:SS"] = wallpaper2,
+--     }
+--   The wallpapers definition can be anything the `schedule_set_function` can read
+--   (what you would place in `args.wallpaper` for this function),
+-- @tparam[opt=`setters.simple`] function args.wallpaper_set_function The set_function used by default
+function setters.simple_schedule(args)
+    local function update_wallpaper()
+        local fake_args = gears.table.join(args, {wallpaper = args.wallpaper[simple_schedule_object.closest_lower_time]})
+        simple_schedule_object.schedule_set_function(fake_args)
+    end
+    if not simple_schedule_object then
+        simple_schedule_object = {}
+        -- initialize the schedule object, so we don't do it for every call
+        simple_schedule_object.schedule_set_function = args.schedule_set_function or setters.simple
+        -- we get the sorted time keys
+        simple_schedule_object.times = {}
+        for k in pairs(args.wallpaper) do table.insert(simple_schedule_object.times, k) end
+        table.sort(simple_schedule_object.times)
+        -- now we get the closest time which is below current time (the current applicable period)
+        local function update_timer()
+            local current_time = os.date("%H:%M:%S")
+            local next_time = simple_schedule_object.times[1]
+            simple_schedule_object.closest_lower_time = simple_schedule_object.times[#(simple_schedule_object.times)]
+            for _, k in ipairs(simple_schedule_object.times) do
+                if k > current_time then
+                    next_time = k
+                    break
+                end
+                simple_schedule_object.closest_lower_time = k
+            end
+            simple_schedule_object.timer.timeout = helpers.time.time_diff(next_time, current_time)
+            if simple_schedule_object.timer.timeout < 0 then
+                -- the next_time is the day after, so we add 24 hours to the timer
+                simple_schedule_object.timer.timeout = simple_schedule_object.timer.timeout + 86400
+            end
+            simple_schedule_object.timer:again()
+            update_wallpaper()
+        end
+        simple_schedule_object.timer = gears.timer {
+            callback = update_timer,
+        }
+        update_timer()
+    else
+        -- if called again (usually when the change_timer is set), we just change the wallpaper depending on current parameters
+        update_wallpaper()
+    end
+end
+
+
+
+
+
+--- Set the AWESOME wallpaper.
+--
+-- @tparam table args The argument table containing the argument below.
+--   @param[opt=`beautiful.bg_normal`] args.colors.bg The bg color.
+--     If the default is used, the color is darkened if `beautiful.bg_normal` is light
+--     or lightned if `beautiful.bg_normal` is dark.
+--   @param[opt=`beautiful.fg_normal`] args.colors.fg The fg color.
+--   @param[opt=`beautiful.fg_focus`] args.colors.alt_fg The alt_fg color.
+--
+-- see beautiful.theme_assets.wallpaper
+function setters.awesome_wallpaper(args)
+    local colors = {bg = beautiful.bg_normal, fg = beautiful.fg_normal, alt_fg = beautiful.bg_focus }
+    colors.bg = helpers.color.is_dark(beautiful.bg_normal)
+        and helpers.color.lighten(colors.bg)
+        or helpers.color.darken(colors.bg)
+    if (type(args.colors) == "table") then
+        colors.bg     = args.colors.bg     or colors.bg
+        colors.fg     = args.colors.fg     or colors.fg
+        colors.alt_fg = args.colors.alt_fg or colors.alt_fg
+    end
+    -- Generate wallpaper:
+    if not args.screen then
+        for s in screen do
+            gears.wallpaper.set(
+                beautiful.theme_assets.wallpaper(colors.bg, colors.fg, colors.alt_fg, s)
+            )
+        end
+    else
+        gears.wallpaper.set(
+            beautiful.theme_assets.wallpaper(colors.bg, colors.fg, colors.alt_fg, args.screen)
+        )
+    end
+end
+
+
+
+--- Setup a wallpaper.
+--
+-- @tparam table args Parameters for the wallpaper. It may also contain all parameters your `args.set_function` needs
+-- @int[opt=nil] args.screen The screen to use (as used in `gears.wallpaper` functions)
+-- @int[opt=nil] args.change_timer Time in seconds for wallpaper changes
+-- @tparam[opt=`setters.awesome` or `setters.simple`] function args.set_function A function to set the wallpaper
+--   It takes args as parameter (the same args as the setup function).
+--   This function is called at `"request::wallpaper"` `screen` signals and at `args.change_timer` timeouts.
+--   There is no obligation, but for consistency, the function should use `args.wallpaper` as a feeder.
+--   If `args.wallpaper` is defined, the default function is `setters.simple`, else it will be `setters.awesome`.
+--
+-- @usage
+--   local wallpaper = require("wallpaper")
+--   wallpaper.setup {
+--       change_timer = 631,  -- Prime number is better
+--       set_function = wallpaper.setters.random,
+--       -- parameters for the random setter
+--       wallpaper = '/data/pictures/wallpapers',
+--       position = "maximized",
+--   }
+--
+-- @see apply
+-- @see prepare_list
+-- @see setters.simple
+function setup(args)
+    local config = args or {}
+    config.set_function = config.set_function or (config.wallpaper and setters.simple or setters.awesome_wallpaper)
+    local function set_wallpaper(s)
+        config.screen = s or config.screen
+        config.set_function(config)
+    end
+
+    if config.change_timer and config.change_timer > 0 then
+        gears.timer {
+            timeout = config.change_timer,
+            call_now = false,
+            autostart = true,
+            callback = function() set_wallpaper() end
+        }
+    end
+
+    screen.connect_signal("request::wallpaper", set_wallpaper)
+end
+
+
+
+
+return {
+    setup = setup,
+    setters = setters,
+    apply = apply,
+    prepare_list = prepare_list,
+}

module/window_swallowing.lua

@@ -2,7 +2,7 @@ local awful = require("awful")
 local gears = require("gears")
 local beautiful = require("beautiful")
 
-local helpers = require(tostring(...):match(".*bling.module") .. ".helpers")
+local helpers = require(tostring(...):match(".*bling") .. ".helpers")
 
 -- It might actually swallow too much, that's why there is a filter option by classname
 -- without the don't-swallow-list it would also swallow for example 
@@ -58,12 +58,12 @@ local function manage_clientspawn(c)
     if (tostring(parent_pid) == tostring(parent_client.pid)) and check_if_swallow(c) then 
 
         c:connect_signal("unmanage", function()
-            helpers.turn_on(parent_client)
+            helpers.client.turn_on(parent_client)
             copy_size(parent_client, c)
         end)
 
         copy_size(c, parent_client)
-        helpers.turn_off(parent_client)
+        helpers.client.turn_off(parent_client)
 
     end
 end

widget/tabbar/modern.lua

@@ -4,7 +4,7 @@ local wibox = require("wibox")
 local beautiful = require("beautiful")
 local xresources = require("beautiful.xresources")
 local dpi = xresources.apply_dpi
-local helpers = require(tostring(...):match(".*bling") .. ".module.helpers")
+local helpers = require(tostring(...):match(".*bling") .. ".helpers")
 
 local bg_normal = beautiful.tabbar_bg_normal or beautiful.bg_normal or "#ffffff"
 local fg_normal = beautiful.tabbar_fg_normal or beautiful.fg_normal or "#000000"
@@ -120,29 +120,29 @@ local function create(c, focused_bool, buttons)
             {
                 tab_content,
                 bg = bg_temp,
-                shape = helpers.prrect(border_radius, true, true, false, false),
+                shape = helpers.shape.prrect(border_radius, true, true, false, false),
                 widget = wibox.container.background
             },
             top = dpi(8),
             widget = wibox.container.margin
         }
 
-        left_shape = helpers.prrect(border_radius, false, false, true, false)
-        right_shape = helpers.prrect(border_radius, false, false, false, true)
+        left_shape = helpers.shape.prrect(border_radius, false, false, true, false)
+        right_shape = helpers.shape.prrect(border_radius, false, false, false, true)
     else
         main_content = wibox.widget {
             {
                 tab_content,
                 bg = bg_temp,
-                shape = helpers.prrect(border_radius, false, false, true, true),
+                shape = helpers.shape.prrect(border_radius, false, false, true, true),
                 widget = wibox.container.background
             },
             bottom = dpi(8),
             widget = wibox.container.margin
         }
 
-        left_shape = helpers.prrect(border_radius, false, true, false, false)
-        right_shape = helpers.prrect(border_radius, true, false, false, false)
+        left_shape = helpers.shape.prrect(border_radius, false, true, false, false)
+        right_shape = helpers.shape.prrect(border_radius, true, false, false, false)
     end
 
     local wid_temp = wibox.widget({