Add documentation for wallpaper

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:
@@ -114,6 +241,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