Merge pull request #3335 from Elv13/imagebox

Extend wibox.widget.imagebox to encompass the required wallpaper API features

lib/wibox/widget/imagebox.lua

@@ -72,22 +72,94 @@ end
 function imagebox:draw(_, cr, width, height)
     if width == 0 or height == 0 or not self._private.default then return end
 
-    -- Set the clip
+    -- For valign = "top" and halign = "left"
-    if self._private.clip_shape then
+    local translate = {
-        cr:clip(self._private.clip_shape(cr, width, height, unpack(self._private.clip_args)))
+        x = 0,
-    end
+        y = 0,
+    }
+
+    local w, h = self._private.default.width, self._private.default.height
 
     if not self._private.resize_forbidden then
-        -- Let's scale the image so that it fits into (width, height)
+        -- That's for the "fit" policy.
-        local w, h = self._private.default.width, self._private.default.height
+        local aspects = {
-        local aspect = math.min(width / w, height / h)
+            w = width / w,
-        cr:scale(aspect, aspect)
+            h = height / h
+        }
+
+        local policy = {
+            w = self._private.horizontal_fit_policy or "auto",
+            h = self._private.vertical_fit_policy or "auto"
+        }
+
+        for _, aspect in ipairs {"w", "h"} do
+            if policy[aspect] == "auto" then
+                aspects[aspect] = math.min(width / w, height / h)
+            elseif policy[aspect] == "none" then
+                aspects[aspect] = 1
+            end
+        end
+
+        if self._private.halign == "center" then
+            translate.x = math.floor((width - w*aspects.w)/2)
+        elseif self._private.halign == "right" then
+            translate.x = math.floor(width - (w*aspects.w))
+        end
+
+        if self._private.valign == "center" then
+            translate.y = math.floor((height - h*aspects.h)/2)
+        elseif self._private.valign == "bottom" then
+            translate.y = math.floor(height - (h*aspects.h))
+        end
+
+        cr:translate(translate.x, translate.y)
+
+        -- Before using the scale, make sure it is below the threshold.
+        local threshold, max_factor = self._private.max_scaling_factor, math.max(aspects.w, aspects.h)
+
+        if threshold and threshold > 0 and threshold < max_factor then
+            aspects.w = (aspects.w*threshold)/max_factor
+            aspects.h = (aspects.h*threshold)/max_factor
+        end
+
+        -- Set the clip
+        if self._private.clip_shape then
+            cr:clip(self._private.clip_shape(cr, w*aspects.w, h*aspects.h, unpack(self._private.clip_args)))
+        end
+
+        cr:scale(aspects.w, aspects.h)
+    else
+        if self._private.halign == "center" then
+            translate.x = math.floor((width - w)/2)
+        elseif self._private.halign == "right" then
+            translate.x = math.floor(width - w)
+        end
+
+        if self._private.valign == "center" then
+            translate.y = math.floor((height - h)/2)
+        elseif self._private.valign == "bottom" then
+            translate.y = math.floor(height - h)
+        end
+
+        cr:translate(translate.x, translate.y)
+
+        -- Set the clip
+        if self._private.clip_shape then
+            cr:clip(self._private.clip_shape(cr, w, h, unpack(self._private.clip_args)))
+        end
     end
 
     if self._private.handle then
         self._private.handle:render_cairo(cr)
     else
         cr:set_source_surface(self._private.image, 0, 0)
+
+        local filter = self._private.scaling_quality
+
+        if filter then
+            cr:get_source():set_filter(cairo.Filter[filter:upper()])
+        end
+
         cr:paint()
     end
 end
@@ -212,6 +284,8 @@ end
 -- A clip shape define an area where the content is displayed and one where it
 -- is trimmed.
 --
+-- @DOC_wibox_widget_imagebox_clip_shape_EXAMPLE@
+--
 -- @property clip_shape
 -- @tparam function|gears.shape clip_shape A `gears.shape` compatible shape function.
 -- @propemits true false
@@ -254,6 +328,156 @@ function imagebox:set_resize(allowed)
     self:emit_signal("property::resize", allowed)
 end
 
+--- Set the horizontal fit policy.
+--
+-- Values are:
+--
+--  * **auto**: Honor the `resize` varible and preserve the aspect ratio (default).
+--  * **none**: Do not resize at all.
+--  * **fit**: Resize to the widget width.
+--
+-- Here is the result for a 22x32 image:
+--
+-- @DOC_wibox_widget_imagebox_horizontal_fit_policy_EXAMPLE@
+--
+--  @property horizontal_fit_policy
+--  @tparam[opt=auto] string horizontal_fit_policy
+--  @propemits true false
+--  @see vertical_fit_policy
+--  @see resize
+
+--- Set the vertical fit policy.
+-- Values are:
+--
+--  * **auto**: Honor the `resize` varible and preserve the aspect ratio (default).
+--  * **none**: Do not resize at all.
+--  * **fit**: Resize to the widget height.
+--
+-- Here is the result for a 32x22 image:
+--
+-- @DOC_wibox_widget_imagebox_vertical_fit_policy_EXAMPLE@
+--
+-- @property vertical_fit_policy
+-- @tparam[opt=auto] string horizontal_fit_policy
+-- @propemits true false
+-- @see horizontal_fit_policy
+-- @see resize
+
+
+--- The vertical alignment.
+--
+-- Possible values are:
+--
+-- * *top*
+-- * *center* (default)
+-- * *bottom*
+--
+-- @DOC_wibox_widget_imagebox_valign_EXAMPLE@
+--
+-- @property valign
+-- @tparam string avlign
+-- @propemits true false
+-- @see wibox.container.place
+-- @see halign
+
+--- The horizontal alignment.
+--
+-- Possible values are:
+--
+-- * *left*
+-- * *center* (default)
+-- * *right*
+--
+-- @DOC_wibox_widget_imagebox_halign_EXAMPLE@
+--
+-- @property halign
+-- @tparam string halign
+-- @propemits true false
+-- @see wibox.container.place
+-- @see valign
+
+--- The maximum scaling factor.
+--
+-- If an image is scaled too much, it gets very blurry. This
+-- property allows to limit the scaling. Use the `valign` and
+-- `halign` to control how the image will be aligned.
+--
+-- In the example below, the original size is 22x22
+--
+-- @DOC_wibox_widget_imagebox_max_scaling_factor_EXAMPLE@
+--
+-- @property max_scaling_factor
+-- @tparam number max_scaling_factor
+-- @propemits true false
+-- @see valign
+-- @see halign
+-- @see scaling_quality
+
+--- Set the scaling aligorithm.
+--
+-- Depending on how the image is used, what is the "correct" way to
+-- scale can change. For example, upscaling a pixel art image should
+-- not make it blurry. However, scaling up a photo should not make it
+-- blocky.
+--
+--<table class='widget_list' border=1>
+-- <tr style='font-weight: bold;'>
+--  <th align='center'>Value</th>
+--  <th align='center'>Description</th>
+-- </tr>
+-- <tr><td>fast</td><td>A high-performance filter</td></tr>
+-- <tr><td>good</td><td>A reasonable-performance filter</td></tr>
+-- <tr><td>best</td><td>The highest-quality available</td></tr>
+-- <tr><td>nearest</td><td>Nearest-neighbor filtering (blocky)</td></tr>
+-- <tr><td>bilinear</td><td>Linear interpolation in two dimensions</td></tr>
+--</table>
+--
+-- The image used in the example below has a resolution of 32x22 and is intentionally
+-- blocky to highlight the difference. It is zoomed by a factor of 3.
+--
+-- @DOC_wibox_widget_imagebox_scaling_quality_EXAMPLE@
+--
+-- @property scaling_quality
+-- @tparam string scaling_quality Either `fast`, `good`, `best`, `nearest` or `bilinear`.
+-- @propemits true false
+-- @see resize
+-- @see horizontal_fit_policy
+-- @see vertical_fit_policy
+-- @see max_scaling_factor
+
+local defaults = {
+    halign                = "left",
+    valign                = "top",
+    horizontal_fit_policy = "auto",
+    vertical_fit_policy   = "auto",
+    max_scaling_factor    = 0,
+    scaling_quality       = "good"
+}
+
+local function get_default(prop, value)
+    if value == nil then return defaults[prop] end
+
+    return value
+end
+
+for prop in pairs(defaults) do
+    imagebox["set_"..prop] = function(self, value)
+        if value == self._private[prop] then return end
+
+        self._private[prop] = get_default(prop, value)
+        self:emit_signal("widget::redraw_needed")
+        self:emit_signal("property::"..prop, self._private[prop])
+    end
+
+    imagebox["get_"..prop] = function(self)
+        if self._private[prop] == nil then
+            return defaults[prop]
+        end
+
+        return self._private[prop]
+    end
+end
+
 --- Returns a new `wibox.widget.imagebox` instance.
 --
 -- This is the constructor of `wibox.widget.imagebox`. It creates a new

tests/examples/wibox/widget/imagebox/clip_shape.lua

@@ -0,0 +1,62 @@
+--DOC_GEN_IMAGE --DOC_HIDE
+local parent = ... --DOC_HIDE
+local wibox  = require("wibox") --DOC_HIDE
+local beautiful = require( "beautiful" )  --DOC_HIDE
+local gears = {shape=require("gears.shape")} --DOC_HIDE
+
+local l = wibox.layout { --DOC_HIDE
+    forced_width  = 380, --DOC_HIDE
+    spacing       = 5, --DOC_HIDE
+    layout        = wibox.layout.flex.vertical --DOC_HIDE
+} --DOC_HIDE
+
+local names = {"circle", "squircle", "rounded_rect"} --DOC_HIDE
+
+for _, resize in ipairs {true, false} do
+    local row = wibox.layout { --DOC_HIDE
+        spacing = 5, --DOC_HIDE
+        layout = wibox.layout.fixed.horizontal --DOC_HIDE
+    } --DOC_HIDE
+
+    row:add(wibox.widget { --DOC_HIDE
+        markup = "<b>resize = "..(resize and "true" or "false").."</b>", --DOC_HIDE
+        forced_width = 80, --DOC_HIDE
+        widget = wibox.widget.textbox --DOC_HIDE
+    }) --DOC_HIDE
+
+    for idx, shape in ipairs {gears.shape.circle, gears.shape.squircle, gears.shape.rounded_rect} do
+        local w = wibox.widget {
+            {
+                {
+                    image         = beautiful.awesome_icon,
+                    forced_height = 32,
+                    forced_width  = 32,
+                    clip_shape    = shape,
+                    resize        = resize,
+                    widget        = wibox.widget.imagebox
+                },
+                widget = wibox.container.place
+            },
+            forced_height = 64, --DOC_HIDE
+            forced_width = 64, --DOC_HIDE
+            widget = wibox.container.background
+        }
+
+
+        row:add(wibox.widget {--DOC_HIDE
+            {--DOC_HIDE
+                markup = "<b>`shape` = "..names[idx].."</b>",--DOC_HIDE
+                widget = wibox.widget.textbox,--DOC_HIDE
+            },--DOC_HIDE
+            w,--DOC_HIDE
+            layout = wibox.layout.fixed.vertical,--DOC_HIDE
+        }) --DOC_HIDE
+    end
+
+    l:add(row) --DOC_HIDE
+end
+
+
+parent:add(l) --DOC_HIDE
+
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/wibox/widget/imagebox/halign.lua

@@ -0,0 +1,58 @@
+--DOC_GEN_IMAGE --DOC_HIDE
+local parent = ... --DOC_HIDE
+local wibox  = require("wibox") --DOC_HIDE
+local beautiful = require( "beautiful" )  --DOC_HIDE
+
+local l = wibox.layout { --DOC_HIDE
+    forced_width  = 360, --DOC_HIDE
+    spacing       = 5, --DOC_HIDE
+    layout        = wibox.layout.flex.vertical --DOC_HIDE
+} --DOC_HIDE
+
+for _, resize in ipairs {true, false} do
+    local row = wibox.layout { --DOC_HIDE
+        spacing = 5, --DOC_HIDE
+        layout = wibox.layout.fixed.horizontal --DOC_HIDE
+    } --DOC_HIDE
+
+    row:add(wibox.widget { --DOC_HIDE
+        markup = "<b>resize = "..(resize and "true" or "false").."</b>", --DOC_HIDE
+        forced_width = 80, --DOC_HIDE
+        widget = wibox.widget.textbox --DOC_HIDE
+    }) --DOC_HIDE
+
+    for _, halign in ipairs {"left", "center", "right"} do
+        local w = wibox.widget {
+            {
+                {
+                    image         = beautiful.awesome_icon,
+                    forced_height = 32,
+                    forced_width  = 32,
+                    halign        = halign,
+                    resize        = resize,
+                    widget        = wibox.widget.imagebox
+                },
+                bg     = beautiful.bg_normal,
+                forced_height = 32, --DOC_HIDE
+                forced_width = 80, --DOC_HIDE
+                widget = wibox.container.background
+            },
+            widget = wibox.container.place
+        }
+
+        row:add(wibox.widget {--DOC_HIDE
+            {--DOC_HIDE
+                markup = "<b>`valign` = "..halign.."</b>",--DOC_HIDE
+                widget = wibox.widget.textbox,--DOC_HIDE
+            },--DOC_HIDE
+            w,--DOC_HIDE
+            layout = wibox.layout.fixed.vertical,--DOC_HIDE
+        }) --DOC_HIDE
+    end
+
+    l:add(row) --DOC_HIDE
+end
+
+parent:add(l) --DOC_HIDE
+
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/wibox/widget/imagebox/horizontal_fit_policy.lua

@@ -0,0 +1,81 @@
+--DOC_HIDE_ALL
+--DOC_GEN_IMAGE
+local parent    = ...
+local wibox     = require( "wibox"     )
+local beautiful = require( "beautiful" )
+local lgi = require("lgi")
+local cairo = lgi.cairo
+
+-- A simple Awesome logo
+local function demo()
+    local img = cairo.ImageSurface.create(cairo.Format.ARGB32, 22, 32)
+    local cr = cairo.Context(img)
+
+    -- Awesome default #555555
+    cr:set_source_rgb(0,0,1)
+    cr:paint()
+
+    cr:set_source_rgb(1,0,0)
+
+    cr:rectangle(0, 15, 22, 2)
+    cr:rectangle(10, 0, 2, 32)
+    cr:fill()
+
+    cr:set_source_rgb(0,1,0)
+
+    cr:arc(11, 16, 8, 0, 2*math.pi)
+    cr:fill()
+
+    return img
+end
+
+
+local function cell_centered_widget(widget)
+    return wibox.widget {
+        widget,
+        valign = 'center',
+        halign = 'center',
+        content_fill_vertical = false,
+        content_fill_horizontal = false,
+        widget = wibox.container.place
+    }
+end
+
+local function build_ib(size, policy)
+    return cell_centered_widget(wibox.widget {
+        {
+            horizontal_fit_policy = policy,
+            forced_height = size,
+            forced_width = size,
+            image  = demo(),
+            widget = wibox.widget.imagebox
+        },
+        forced_width  = size + 2,
+        forced_height = size + 2,
+        color         = beautiful.border_color,
+        margins       = 1,
+        widget        = wibox.container.margin
+    })
+end
+
+
+local l = wibox.widget {
+    homogeneous   = false,
+    spacing       = 5,
+    layout        = wibox.layout.grid,
+}
+parent:add(l)
+
+l:add_widget_at(wibox.widget.textbox('horizontal_fit_policy = "auto"'), 1, 1)
+l:add_widget_at(wibox.widget.textbox('horizontal_fit_policy = "none"'), 2, 1)
+l:add_widget_at(wibox.widget.textbox('horizontal_fit_policy = "fit"'), 3, 1)
+l:add_widget_at(wibox.widget.textbox('imagebox size'), 4, 1)
+
+for i,size in ipairs({16, 32, 64}) do
+    l:add_widget_at(build_ib(size, "auto"), 1, i + 1)
+    l:add_widget_at(build_ib(size, "none"), 2, i + 1)
+    l:add_widget_at(build_ib(size, "fit" ), 3, i + 1)
+    l:add_widget_at(cell_centered_widget(wibox.widget.textbox(size..'x'..size)), 4, i + 1)
+end
+
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/wibox/widget/imagebox/max_scaling_factor.lua

@@ -0,0 +1,53 @@
+--DOC_HIDE_ALL
+--DOC_GEN_IMAGE
+local parent    = ...
+local wibox     = require( "wibox"     )
+local beautiful = require( "beautiful" )
+
+local function cell_centered_widget(widget)
+    return wibox.widget {
+        widget,
+        valign = 'center',
+        halign = 'center',
+        content_fill_vertical = false,
+        content_fill_horizontal = false,
+        widget = wibox.container.place
+    }
+end
+
+local function build_ib(size, factor)
+    return cell_centered_widget(wibox.widget {
+        {
+            forced_height = size,
+            forced_width = size,
+            max_scaling_factor = factor,
+            image  = beautiful.awesome_icon,
+            widget = wibox.widget.imagebox
+        },
+        forced_width  = size + 2,
+        forced_height = size + 2,
+        color         = beautiful.border_color,
+        margins       = 1,
+        widget        = wibox.container.margin
+    })
+end
+
+
+local l = wibox.widget {
+    homogeneous   = false,
+    spacing       = 5,
+    layout        = wibox.layout.grid,
+}
+parent:add(l)
+
+l:add_widget_at(cell_centered_widget(wibox.widget.textbox('max_scaling_factor = nil')), 1, 1)
+l:add_widget_at(cell_centered_widget(wibox.widget.textbox('max_scaling_factor = 2')), 2, 1)
+l:add_widget_at(cell_centered_widget(wibox.widget.textbox('imagebox size')), 3, 1)
+
+for i,size in ipairs({16, 32, 64}) do
+    l:add_widget_at(build_ib(size, nil), 1, i + 1)
+    l:add_widget_at(build_ib(size, 2), 2, i + 1)
+    l:add_widget_at(cell_centered_widget(wibox.widget.textbox(size..'x'..size)), 3, i + 1)
+end
+
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/wibox/widget/imagebox/resize.lua

@@ -16,12 +16,19 @@ local function cell_centered_widget(widget)
 end
 
 local function build_ib(size, resize)
-    return cell_centered_widget({
+    return cell_centered_widget(wibox.widget {
+        {
             resize = resize,
-        forced_width = size,
             forced_height = size,
+            forced_width = size,
             image  = beautiful.awesome_icon,
             widget = wibox.widget.imagebox
+        },
+        forced_width  = size + 2,
+        forced_height = size + 2,
+        color         = beautiful.border_color,
+        margins       = 1,
+        widget        = wibox.container.margin
     })
 end
 

tests/examples/wibox/widget/imagebox/scaling_quality.lua

@@ -0,0 +1,77 @@
+--DOC_GEN_IMAGE --DOC_HIDE
+local parent = ... --DOC_HIDE
+local wibox  = require("wibox") --DOC_HIDE
+local lgi = require("lgi")--DOC_HIDE
+local cairo = lgi.cairo --DOC_HIDE
+
+--DOC_HIDE A simple Awesome logo
+local function demo()--DOC_HIDE
+    local img = cairo.ImageSurface.create(cairo.Format.ARGB32, 32, 22)--DOC_HIDE
+    local cr = cairo.Context(img)--DOC_HIDE
+    cr:set_antialias(cairo.Antialias.NONE) --DOC_HIDE
+
+    -- Awesome default #555555--DOC_HIDE
+    cr:set_source_rgb(0,0,1)--DOC_HIDE
+    cr:paint() --DOC_HIDE
+
+    cr:set_source_rgb(1,0,0)--DOC_HIDE
+
+    cr:rectangle(0, 10, 32, 2)--DOC_HIDE
+    cr:rectangle(15, 0, 2, 22)--DOC_HIDE
+    cr:fill()--DOC_HIDE
+
+    cr:set_source_rgb(0,1,0)--DOC_HIDE
+
+    cr:arc(16, 11, 8, 0, 2*math.pi)--DOC_HIDE
+    cr:fill()--DOC_HIDE
+
+    return img--DOC_HIDE
+end--DOC_HIDE
+
+local img = demo () --DOC_HIDE
+
+local l = wibox.layout { --DOC_HIDE
+    -- forced_width  = 720, --DOC_HIDE
+    spacing       = 5, --DOC_HIDE
+    layout        = wibox.layout.flex.vertical --DOC_HIDE
+} --DOC_HIDE
+
+ for _, quality in ipairs {"fast", "good", "best", "nearest", "bilinear"} do
+    local w = wibox.widget {
+        {
+            {
+                image           = img,
+                forced_height   = 64,
+                forced_width    = 96,
+                scaling_quality = quality,
+                widget          = wibox.widget.imagebox
+            },
+            widget = wibox.container.place
+        },
+        -- forced_height = 96, --DOC_HIDE
+        -- forced_width = 96, --DOC_HIDE
+        widget = wibox.container.background
+    }
+
+    --DOC_HIDE SVG doesn't support those mode, so rasterize everything.
+    local raster = wibox.widget.draw_to_image_surface(w, 96, 64) --DOC_HIDE
+
+    l:add(wibox.widget {--DOC_HIDE
+        {--DOC_HIDE
+            markup = "<b>`scaling_quality` = "..quality.."</b>",--DOC_HIDE
+            widget = wibox.widget.textbox,--DOC_HIDE
+        },--DOC_HIDE
+        { --DOC_HIDE
+            image = raster, --DOC_HIDE
+            forced_height   = 64, --DOC_HIDE
+            forced_width    = 96, --DOC_HIDE
+            widget = wibox.widget.imagebox --DOC_HIDE
+        },--DOC_HIDE
+        layout = wibox.layout.fixed.vertical,--DOC_HIDE
+    }) --DOC_HIDE
+ end
+
+
+parent:add(l) --DOC_HIDE
+
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/wibox/widget/imagebox/valign.lua

@@ -0,0 +1,58 @@
+--DOC_GEN_IMAGE --DOC_HIDE
+local parent = ... --DOC_HIDE
+local wibox  = require("wibox") --DOC_HIDE
+local beautiful = require( "beautiful" )  --DOC_HIDE
+
+local l = wibox.layout { --DOC_HIDE
+    forced_width  = 340, --DOC_HIDE
+    spacing       = 5, --DOC_HIDE
+    layout        = wibox.layout.flex.vertical --DOC_HIDE
+} --DOC_HIDE
+
+for _, resize in ipairs {true, false} do
+    local row = wibox.layout { --DOC_HIDE
+        spacing = 5, --DOC_HIDE
+        layout = wibox.layout.fixed.horizontal --DOC_HIDE
+    } --DOC_HIDE
+
+    row:add(wibox.widget { --DOC_HIDE
+        markup = "<b>resize = "..(resize and "true" or "false").."</b>", --DOC_HIDE
+        forced_width = 80, --DOC_HIDE
+        widget = wibox.widget.textbox --DOC_HIDE
+    }) --DOC_HIDE
+
+    for _, valign in ipairs {"top", "center", "bottom"} do
+        local w = wibox.widget {
+            {
+                {
+                    image         = beautiful.awesome_icon,
+                    forced_height = 32,
+                    forced_width  = 32,
+                    valign        = valign,
+                    resize        = resize,
+                    widget        = wibox.widget.imagebox
+                },
+                bg     = beautiful.bg_normal,
+                forced_height = 80, --DOC_HIDE
+                forced_width = 32, --DOC_HIDE
+                widget = wibox.container.background
+            },
+            widget = wibox.container.place
+        }
+
+        row:add(wibox.widget {--DOC_HIDE
+            {--DOC_HIDE
+                markup = "<b>`valign` = "..valign.."</b>",--DOC_HIDE
+                widget = wibox.widget.textbox,--DOC_HIDE
+            },--DOC_HIDE
+            w,--DOC_HIDE
+            layout = wibox.layout.fixed.vertical,--DOC_HIDE
+        }) --DOC_HIDE
+    end
+
+    l:add(row) --DOC_HIDE
+end
+
+parent:add(l) --DOC_HIDE
+
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/wibox/widget/imagebox/vertical_fit_policy.lua

@@ -0,0 +1,81 @@
+--DOC_HIDE_ALL
+--DOC_GEN_IMAGE
+local parent    = ...
+local wibox     = require( "wibox"     )
+local beautiful = require( "beautiful" )
+local lgi = require("lgi")
+local cairo = lgi.cairo
+
+-- A simple Awesome logo
+local function demo()
+    local img = cairo.ImageSurface.create(cairo.Format.ARGB32, 32, 22)
+    local cr = cairo.Context(img)
+
+    -- Awesome default #555555
+    cr:set_source_rgb(0,0,1)
+    cr:paint()
+
+    cr:set_source_rgb(1,0,0)
+
+    cr:rectangle(0, 10, 32, 2)
+    cr:rectangle(15, 0, 2, 22)
+    cr:fill()
+
+    cr:set_source_rgb(0,1,0)
+
+    cr:arc(16, 11, 8, 0, 2*math.pi)
+    cr:fill()
+
+    return img
+end
+
+
+local function cell_centered_widget(widget)
+    return wibox.widget {
+        widget,
+        valign = 'center',
+        halign = 'center',
+        content_fill_vertical = false,
+        content_fill_horizontal = false,
+        widget = wibox.container.place
+    }
+end
+
+local function build_ib(size, policy)
+    return cell_centered_widget(wibox.widget {
+        {
+            vertical_fit_policy = policy,
+            forced_height = size,
+            forced_width = size,
+            image  = demo(),
+            widget = wibox.widget.imagebox
+        },
+        forced_width  = size + 2,
+        forced_height = size + 2,
+        color         = beautiful.border_color,
+        margins       = 1,
+        widget        = wibox.container.margin
+    })
+end
+
+
+local l = wibox.widget {
+    homogeneous   = false,
+    spacing       = 5,
+    layout        = wibox.layout.grid,
+}
+parent:add(l)
+
+l:add_widget_at(wibox.widget.textbox('vertical_fit_policy = "auto"'), 1, 1)
+l:add_widget_at(wibox.widget.textbox('versical_fit_policy = "none"'), 2, 1)
+l:add_widget_at(wibox.widget.textbox('vertical_fit_policy = "fit"'), 3, 1)
+l:add_widget_at(wibox.widget.textbox('imagebox size'), 4, 1)
+
+for i,size in ipairs({16, 32, 64}) do
+    l:add_widget_at(build_ib(size, "auto"), 1, i + 1)
+    l:add_widget_at(build_ib(size, "none"), 2, i + 1)
+    l:add_widget_at(build_ib(size, "fit" ), 3, i + 1)
+    l:add_widget_at(cell_centered_widget(wibox.widget.textbox(size..'x'..size)), 4, i + 1)
+end
+
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80