bling/docs/module/wall.md

🎇 Wallpaper Easy Setup

This is a simple-to-use, extensible, declarative wallpaper manager.

Practical Examples

-- 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 = bling.module.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
}

-- setup for multiple screens at once
-- the 'screen' argument can be a table of screen objects
bling.module.wallpaper.setup {
    set_function = bling.module.wallpaper.setters.random,
    screen = screen, -- The awesome 'screen' variable is an array of all screen objects
    wallpaper = {"/path/to/a/folder", "/path/to/another/folder"},
    change_timer = 631
}

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

To set up for multiple screens, two possible methods are:

• Call the setup function for each screen, passing the appropriate configuration and screen arg
• Call the setup function once, passing a table of screens as the screen arg. This applies the same configuration to all screens in the table Note: Multiple screen setup only works for the simple and random setters

-- 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:

-- Default parameters
bling.module.wallpaper.setup {
    screen = nil,       -- the screen to apply the wallpaper, as seen in gears.wallpaper functions
    screens = nil,      -- an array of screens to apply the wallpaper on. If 'screen' is also provided, this is overridden
    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 for more details.