awful.screenshot: Allow to export widgets instead of files.

Useful for alt-tab widgets and CDE / E16 style Iconified clients.

lib/awful/screenshot.lua

@@ -563,6 +563,21 @@ end
 -- @negativeallowed false
 -- @propemits true false
 
+--- Export this screenshot as an `wibox.widget.imagebox` instead of a file.
+--
+-- This can be used to place the screenshot in a `wibox`, `awful.popup`
+-- or `awful.wibar`. Note that this isn't a live view of the object, you have
+-- to call `:refresh()` to update the content.
+--
+-- Note that it only makes sense when only 1 surface is exported by the
+-- screenhot. If that doesn't work for your use case, consider making multiple
+-- `awful.screenshot` objects.
+--
+-- @property content_widget
+-- @tparam wibox.widget.imagebox content_widget
+-- @readonly
+-- @propertydefault Autogenerated on first access.
+
 local defaults = {
     prefix                  = "Screenshot-",
     directory               = screenshot_validation.directory(os.getenv("HOME")),
@@ -620,14 +635,9 @@ function module:get_surfaces()
     return ret
 end
 
-function module:get_surfaces()
+function module:get_surface()
-    local ret = {}
+    local pair = select(2, next(self._private.surfaces or {}))
-
+    return pair and pair.surface
-    for _, surface in pairs(self._private.surfaces or {}) do
-        table.insert(ret, surface.surface)
-    end
-
-    return ret
 end
 
 function module:get_keygrabber()
@@ -735,9 +745,22 @@ function module:set_auto_save_delay(value)
     self:emit_signal("timer::started")
 end
 
+function module:get_content_widget()
+    if not self._private.output_imagebox then
+        self._private.output_imagebox = wibox.widget.imagebox()
+    end
+
+    local s = self.surface
+
+    if s then
+        self._private.output_imagebox.image = s
+    end
+
+    return self._private.output_imagebox
+end
+
 --- Take new screenshot(s) now.
 --
---
 -- @method refresh
 -- @treturn table A table with the method name as key and the images as value.
 -- @see save
@@ -766,6 +789,10 @@ function module:refresh()
 
     end
 
+    if self._private.output_imagebox then
+        self._private.output_imagebox.image = self.surface
+    end
+
     return self.surfaces
 end