doc: Add a memento widget for the wibox template.

tests/examples/wibox/template.lua

@@ -3,6 +3,37 @@ require("_common_template")(...)
 
 local wibox   = require( "wibox"         )
 local surface = require( "gears.surface" )
+local cairo = require("lgi").cairo
+
+--- Create a copy of the widget frozen in time.
+-- This is useful whe the global state is modified between the time this is
+-- called and the time the final output is rendered.
+function _memento(wdg, width, height, context, force) -- luacheck: globals _memento
+    context = context or {dpi=96}
+
+    local w, h = wdg:fit(context, width or 9999, height or 9999)
+
+    w, h = math.min(force and width or w,  width or 9999), math.min(force and height or h, height or 9999)
+
+    local memento = cairo.RecordingSurface(
+        cairo.Content.CAIRO_FORMAT_ARGB32,
+        cairo.Rectangle { x = 0, y = 0, width = w, height = h }
+    )
+
+    local cr = cairo.Context(memento)
+
+    wibox.widget.draw_to_cairo_context(wdg, cr, w, h, context)
+
+    return wibox.widget {
+        fit = function()
+            return w, h
+        end,
+        draw = function(_, _, cr2)
+            cr2:set_source_surface(memento)
+            cr2:paint()
+        end
+    }
+end
 
 -- This is the main widget the tests will use as top level
 local container = wibox.layout.fixed.vertical()