diff --git a/README.md b/README.md index c0d1367..b7d323e 100644 --- a/README.md +++ b/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