imagebox: Enable the property system

And add the missing documentation

lib/wibox/widget/imagebox.lua

@@ -9,8 +9,8 @@
 
 local base = require("wibox.widget.base")
 local surface = require("gears.surface")
+local util = require("awful.util")
 local setmetatable = setmetatable
-local pairs = pairs
 local type = type
 local print = print
 local unpack = unpack or table.unpack -- luacheck: globals unpack (compatibility with Lua 5.1)
@@ -19,13 +19,13 @@ local imagebox = { mt = {} }
 
 -- Draw an imagebox with the given cairo context in the given geometry.
 function imagebox:draw(_, cr, width, height)
-    if not self._image then return end
+    if not self._private.image then return end
     if width == 0 or height == 0 then return end
 
-    if not self.resize_forbidden then
+    if not self._private.resize_forbidden then
         -- Let's scale the image so that it fits into (width, height)
-        local w = self._image:get_width()
+        local w = self._private.image:get_width()
-        local h = self._image:get_height()
+        local h = self._private.image:get_height()
         local aspect = width / w
         local aspect_h = height / h
         if aspect > aspect_h then aspect = aspect_h end
@@ -34,22 +34,22 @@ function imagebox:draw(_, cr, width, height)
     end
 
     -- Set the clip
-    if self._clip_shape then
+    if self._private.clip_shape then
-        cr:clip(self._clip_shape(cr, width, height, unpack(self._clip_args)))
+        cr:clip(self._private.clip_shape(cr, width, height, unpack(self._private.clip_args)))
     end
 
-    cr:set_source_surface(self._image, 0, 0)
+    cr:set_source_surface(self._private.image, 0, 0)
     cr:paint()
 end
 
 -- Fit the imagebox into the given geometry
 function imagebox:fit(_, width, height)
-    if not self._image then
+    if not self._private.image then
         return 0, 0
     end
 
-    local w = self._image:get_width()
+    local w = self._private.image:get_width()
-    local h = self._image:get_height()
+    local h = self._private.image:get_height()
 
     if w > width then
         h = h * width / w
@@ -64,7 +64,7 @@ function imagebox:fit(_, width, height)
         return 0, 0
     end
 
-    if not self.resize_forbidden then
+    if not self._private.resize_forbidden then
         local aspect = width / w
         local aspect_h = height / h
 
@@ -78,9 +78,11 @@ function imagebox:fit(_, width, height)
 end
 
 --- Set an imagebox' image
+-- @property image
 -- @param image Either a string or a cairo image surface. A string is
 --   interpreted as the path to a png image file.
 -- @return true on success, false if the image cannot be used
+
 function imagebox:set_image(image)
     if type(image) == "string" then
         image = surface.load(image)
@@ -100,19 +102,28 @@ function imagebox:set_image(image)
         end
     end
 
-    if self._image == image then
+    if self._private.image == image then
         -- The image could have been modified, so better redraw
         self:emit_signal("widget::redraw_needed")
         return
     end
 
-    self._image = image
+    self._private.image = image
 
     self:emit_signal("widget::redraw_needed")
     self:emit_signal("widget::layout_changed")
     return true
 end
 
+--- Set a clip shape for this imagebox
+-- A clip shape define an area where the content is displayed and one where it
+-- is trimmed.
+--
+-- @property clip_shape
+-- @param clip_shape A `gears_shape` compatible shape function
+-- @see gears.shape
+-- @see set_clip_shape
+
 --- Set a clip shape for this imagebox
 -- A clip shape define an area where the content is displayed and one where it
 -- is trimmed.
@@ -120,17 +131,21 @@ end
 -- Any other parameters will be passed to the clip shape function
 --
 -- @param clip_shape A `gears_shape` compatible shape function
+-- @see gears.shape
+-- @see clip_shape
 function imagebox:set_clip_shape(clip_shape, ...)
-    self._clip_shape = clip_shape
+    self._private.clip_shape = clip_shape
-    self._clip_args = {...}
+    self._private.clip_args = {...}
     self:emit_signal("widget::redraw_needed")
 end
 
 --- Should the image be resized to fit into the available space?
+-- @property resize
 -- @param allowed If false, the image will be clipped, else it will be resized
 --   to fit into the available space.
+
 function imagebox:set_resize(allowed)
-    self.resize_forbidden = not allowed
+    self._private.resize_forbidden = not allowed
     self:emit_signal("widget::redraw_needed")
     self:emit_signal("widget::layout_changed")
 end
@@ -144,13 +159,9 @@ end
 -- @treturn table A new `imagebox`
 -- @function wibox.widget.imagebox
 local function new(image, resize_allowed, clip_shape)
-    local ret = base.make_widget()
+    local ret = base.make_widget(nil, nil, {enable_properties = true})
 
-    for k, v in pairs(imagebox) do
+    util.table.crush(ret, imagebox, true)
-        if type(v) == "function" then
-            ret[k] = v
-        end
-    end
 
     if image then
         ret:set_image(image)
@@ -159,8 +170,8 @@ local function new(image, resize_allowed, clip_shape)
         ret:set_resize(resize_allowed)
     end
 
-    ret._clip_shape = clip_shape
+    ret._private.clip_shape = clip_shape
-    ret._clip_args = {}
+    ret._private.clip_args = {}
 
     return ret
 end
@@ -169,6 +180,10 @@ function imagebox.mt:__call(...)
     return new(...)
 end
 
+--@DOC_widget_COMMON@
+
+--@DOC_object_COMMON@
+
 return setmetatable(imagebox, imagebox.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/test-awful-widget-button.lua

@@ -52,7 +52,7 @@ table.insert(steps, function()
 
     awful.placement.centered(w)
 
-    img = button._image
+    img = button._private.image
     assert(img)
 
     return true
@@ -68,7 +68,7 @@ table.insert(steps, function()
 end)
 
 table.insert(steps, function()
-    assert(button._image ~= img)
+    assert(button._private.image ~= img)
 
     return true
 end)
@@ -77,14 +77,14 @@ end)
 table.insert(steps, function()
     root.fake_input("button_release", 1)
 
-    assert(button._image ~= img)
+    assert(button._private.image ~= img)
 
     return true
 end)
 
 -- Test a button press/release outside of the widget
 table.insert(steps, function()
-    assert(button._image == img)
+    assert(button._private.image == img)
 
     root.fake_input("button_press", 1)
 
@@ -92,14 +92,14 @@ table.insert(steps, function()
 end)
 
 table.insert(steps, function()
-    assert(button._image ~= img)
+    assert(button._private.image ~= img)
 
     return true
 end)
 
 table.insert(steps, function()
     -- just make sure the button is not released for nothing
-    assert(button._image ~= img)
+    assert(button._private.image ~= img)
 
     -- test if the button is released when the mouse move out
     awful.placement.right(mouse--[[, {parent = w}]])
@@ -109,7 +109,7 @@ table.insert(steps, function()
 end)
 
 table.insert(steps, function()
-    assert(button._image == img)
+    assert(button._private.image == img)
 
     return true
 end)