From 70cd293839e4a1325c4e75eea300f458dba0219b Mon Sep 17 00:00:00 2001
From: Emmanuel Lepage Vallee <elv1313@gmail.com>
Date: Thu, 16 Sep 2021 01:03:10 -0700
Subject: [PATCH] doc: Integrate `awful.wallpaper` into the guides.

---
 docs/03-declarative-layout.md             |  4 ++
 docs/05-awesomerc.md.lua                  |  9 +++
 tests/examples/awful/popup/wiboxtypes.lua | 80 ++++++++++++++++++++++-
 3 files changed, 92 insertions(+), 1 deletion(-)

diff --git a/docs/03-declarative-layout.md b/docs/03-declarative-layout.md
index 12143b54..1555a7c0 100644
--- a/docs/03-declarative-layout.md
+++ b/docs/03-declarative-layout.md
@@ -124,6 +124,10 @@ to an object such as the mouse.
 The `naughty.layout.box` allows to provide custom widgets to use within the
 notifications.
 
+The `awful.wallpaper` provides a non-intereactive "backgroud" for one or more
+`screen`. While it uses normal widget, it will not automatically be repainted
+if they change. It will also not provide any mouse events.
+
 Finally, the `awful.titlebar`, while not technically a real `wibox`, acts
 exactly the same way and allows to attach widgets on each side of clients.
 
diff --git a/docs/05-awesomerc.md.lua b/docs/05-awesomerc.md.lua
index 0fc005d0..783f58f8 100644
--- a/docs/05-awesomerc.md.lua
+++ b/docs/05-awesomerc.md.lua
@@ -72,6 +72,15 @@ variables such as `bg_normal`. To get a list of all official variables, see
 the [appearance guide](../documentation/06-appearance.md.html).
 ]]
 
+sections.DOC_WALLPAPER = [[
+The AwesomeWM wallpaper module, `awful.wallpaper` support both per-screen wallpaper
+and wallpaper across multiple screens. In the default configuration, `request::wallpaper`
+is emitted everytime a screen is added, moved, resized or when the bars
+(`awful.wibar`) are moved.
+
+This is will suited for single-screen wallpaper. If you wish to use multi-screen wallpaper,
+it is better to create a global wallpaper object and edit it when the screen change.
+]]
 
 sections.DOC_DEFAULT_APPLICATIONS = [[
  &nbsp;
diff --git a/tests/examples/awful/popup/wiboxtypes.lua b/tests/examples/awful/popup/wiboxtypes.lua
index c6fa28d9..ccbef7ba 100644
--- a/tests/examples/awful/popup/wiboxtypes.lua
+++ b/tests/examples/awful/popup/wiboxtypes.lua
@@ -8,6 +8,7 @@ local gears     = require("gears")
 local naughty   = require("naughty")
 local wibox     = require("wibox")
 local beautiful = require("beautiful") --DOC_HIDE
+local assets    = require("beautiful.theme_assets")
 local look      = require("_default_look")
 
 screen[1]._resize {width = 640, height = 480}
@@ -17,6 +18,78 @@ screen[1]._resize {width = 640, height = 480}
 
 local c = client.gen_fake {hide_first=true}
 
+-- Don't use `awful.wallpaper` to avoid rasterizing the background.
+
+local wallpaper = wibox {
+    below = true,
+    shape = gears.shape.octogon,
+    visible = true,
+    bg = "#00000000",
+}
+
+awful.placement.maximize(wallpaper)
+
+wallpaper.widget = wibox.widget {
+    fit = function(_, _, width, height)
+        return width, height
+    end,
+    draw = function(_, _, cr, width, height)
+        cr:translate(width - 80, 60)
+        assets.gen_awesome_name(
+            cr, height - 40, "#ffffff", beautiful.bg_normal, beautiful.bg_normal
+        )
+    end,
+    widget = wibox.widget.base.make_widget()
+}
+
+local p = awful.popup {
+    widget = wibox.widget {
+        { text   = "Item", widget = wibox.widget.textbox },
+        {
+            {
+                text   = "Selected",
+                widget = wibox.widget.textbox
+            },
+            bg = beautiful.bg_highlight,
+            widget = wibox.container.background
+        },
+        { text   = "Item", widget = wibox.widget.textbox },
+        forced_width = 100,
+        widget = wibox.layout.fixed.vertical
+    },
+    border_color = beautiful.border_color,
+    border_width = 1,
+    x = 50,
+    y = 200,
+}
+
+
+p:_apply_size_now()
+require("gears.timer").run_delayed_calls_now()
+p._drawable._do_redraw()
+
+require("gears.timer").delayed_call(function()
+    -- Get the 4th textbox
+    local list = p:find_widgets(30, 40)
+    mouse.coords {x= 120, y=225}
+    mouse.push_history()
+    local textboxinstance = list[#list]
+
+    local p2 = awful.popup {
+        widget = wibox.widget {
+            text = "Submenu",
+            forced_height = 20,
+            forced_width = 70,
+            widget = wibox.widget.textbox
+        },
+        border_color  = beautiful.border_color,
+        preferred_positions = "right",
+        border_width  = 1,
+    }
+    p2:move_next_to(textboxinstance, "right")
+end)
+
+
 c:geometry {
     x      = 50,
     y      = 350,
@@ -97,6 +170,7 @@ wibox {
     width = 50,
     height = 50,
     shape = gears.shape.octogon,
+    visible = true,
     color = "#0000ff",
     x = 570,
     y = 410,
@@ -188,13 +262,17 @@ create_info("awful.tooltip", 30, 130, 100, 30)
 create_info("awful.popup", 450, 240, 100, 30)
 create_info("naughty.layout.box", 255, 110, 130, 30)
 create_info("Standard `wibox`", 420, 420, 130, 30)
+create_info("awful.wallpaper", 420, 330, 110, 30)
+create_info("awful.menu", 60, 270, 80, 30)
 
 create_line(150, 10, 150, 55)
 create_line(75, 100, 75, 135)
 create_line(545, 432, 575, 432)
 create_line(500, 165, 500, 245)
-create_line(390, 250, 450, 250)
+create_line(380, 250, 450, 250)
 create_line(190, 365, 255, 365)
 create_line(320, 60, 320, 110)
+create_line(525, 345, 570, 345)
+create_line(100, 240, 100, 270)
 
 --DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80