awful.screen: Deprecate functions, add methods

lib/awful/layout/init.lua

@@ -11,7 +11,6 @@
 local ipairs = ipairs
 local type = type
 local util = require("awful.util")
-local ascreen = require("awful.screen")
 local capi = {
     screen = screen,
     mouse  = mouse,
@@ -138,16 +137,16 @@ function layout.parameters(t, screen)
 
     local useless_gap = t and tag.getgap(t, #client.tiled(screen)) or 0
 
-    p.workarea = ascreen.get_bounding_geometry(screen, {
+    p.workarea = screen:get_bounding_geometry {
         honor_padding  = true,
         honor_workarea = true,
         margins        = useless_gap,
-    })
+    }
 
     p.geometry    = screen.geometry
     p.clients     = client.tiled(screen)
     p.screen      = screen.index
-    p.padding     = ascreen.padding(screen)
+    p.padding     = screen.padding
     p.useless_gap = useless_gap
 
     return p

lib/awful/placement.lua

@@ -19,7 +19,7 @@
 --
 -- **honor_padding** (*boolean*):
 --
---  Take the screen padding into account (see `awful.screen.padding`)
+--  Take the screen padding into account (see `screen.padding`)
 --
 -- **tag** (*tag*):
 --
@@ -158,7 +158,7 @@ local function geometry_common(obj, args, new_geo, ignore_border_width)
         end
 
         -- It is a screen, it doesn't support setting new sizes.
-        return a_screen.get_bounding_geometry(obj, args)
+        return obj:get_bounding_geometry(args)
     else
         assert(false, "Invalid object")
     end

lib/awful/screen.lua

@@ -45,13 +45,25 @@ local function apply_geometry_ajustments(geo, delta)
 end
 
 --- Get the square distance between a `screen` and a point
+-- @deprecated awful.screen.getdistance_sq
 -- @param s Screen
 -- @param x X coordinate of point
 -- @param y Y coordinate of point
 -- @return The squared distance of the screen to the provided point
 function screen.getdistance_sq(s, x, y)
-    s = get_screen(s)
-    local geom = s.geometry
+    util.deprecate "Use s:get_square_distance(x, y) instead of awful.screen.getdistance_sq"
+
+    return screen.object.get_square_distance(s, x, y)
+end
+
+--- Get the square distance between a `screen` and a point
+-- @function screen.get_square_distance
+-- @tparam number x X coordinate of point
+-- @tparam number y Y coordinate of point
+-- @treturn number The squared distance of the screen to the provided point
+function screen.object.get_square_distance(self, x, y)
+    self = get_screen(self)
+    local geom = self.geometry
     local dist_x, dist_y = 0, 0
     if x < geom.x then
         dist_x = geom.x - x
@@ -75,9 +87,9 @@ end
 -- @param y The y coordinate
 function screen.getbycoord(x, y)
     local s = capi.screen[1]
-    local dist = screen.getdistance_sq(s, x, y)
+    local dist = screen.object.get_square_distance(s, x, y)
     for i in capi.screen do
-        local d = screen.getdistance_sq(i, x, y)
+        local d = screen.object.get_square_distance(i, x, y)
         if d < dist then
             s, dist = capi.screen[i], d
         end
@@ -153,12 +165,51 @@ function screen.focus_relative(i)
 end
 
 --- Get or set the screen padding.
+-- @deprecated awful.screen.padding
 -- @param _screen The screen object to change the padding on
 -- @param[opt=nil] padding The padding, a table with 'top', 'left', 'right' and/or
 -- 'bottom' or a number value to apply set the same padding on all sides. Can be
 --  nil if you only want to retrieve padding
 -- @treturn table A table with left, right, top and bottom number values.
+-- @see padding
 function screen.padding(_screen, padding)
+    util.deprecate "Use _screen.padding = value instead of awful.screen.padding"
+
+    if padding then
+        screen.object.set_padding(_screen, padding)
+    end
+
+    return screen.object.get_padding(_screen)
+end
+
+--- The screen padding.
+-- Add a "buffer" section on each side of the screen where the tiled client
+-- wont be.
+--
+-- **Signal:**
+--
+-- * *property::padding*
+--
+-- @property padding
+-- @param table
+-- @tfield integer table.x The horizontal position
+-- @tfield integer table.y The vertical position
+-- @tfield integer table.width The width
+-- @tfield integer table.height The height
+
+function screen.object.get_padding(self)
+    local p = data.padding[self] or {}
+
+    -- Create a copy to avoid accidental mutation and nil values
+    return {
+        left   = p.left   or 0,
+        right  = p.right  or 0,
+        top    = p.top    or 0,
+        bottom = p.bottom or 0,
+    }
+end
+
+function screen.object.set_padding(self, padding)
     if type(padding) == "number" then
         padding = {
             left   = padding,
@@ -168,21 +219,11 @@ function screen.padding(_screen, padding)
         }
     end
 
-    _screen = get_screen(_screen)
+    self = get_screen(self)
     if padding then
-        data.padding[_screen] = padding
-        _screen:emit_signal("padding")
+        data.padding[self] = padding
+        self:emit_signal("padding")
     end
-
-    local p = data.padding[_screen] or {}
-
-    -- Create a copy to avoid accidental mutation and nil values
-    return {
-        left   = p.left   or 0,
-        right  = p.right  or 0,
-        top    = p.top    or 0,
-        bottom = p.bottom or 0,
-    }
 end
 
 --- The defaults arguments for `awful.screen.focused`
@@ -197,7 +238,7 @@ end
 -- @tparam[opt] table args
 -- @tparam[opt=false] boolean args.client Use the client screen instead of the
 --   mouse screen.
--- @tparam[opt=true] boolean args.screen Use the mouse screen
+-- @tparam[opt=true] boolean args.mouse Use the mouse screen
 -- @treturn ?screen The focused screen object, or `nil` in case no screen is
 --   present currently.
 function screen.focused(args)
@@ -219,24 +260,31 @@ end
 -- * **bounding_rect**: A bounding rectangle. This parameter is incompatible with
 --    `honor_workarea`.
 --
--- @tparam[opt=mouse.screen] screen s A screen
+-- @function screen.get_bounding_geometry
 -- @tparam[opt={}] table args The arguments
 -- @treturn table A table with *x*, *y*, *width* and *height*.
-function screen.get_bounding_geometry(s, args)
+-- @usage local geo = screen:get_bounding_geometry {
+--     honor_padding  = true,
+--     honor_workarea = true,
+--     margins        = {
+--          left = 20,
+--     },
+-- }
+function screen.object.get_bounding_geometry(self, args)
     args = args or {}
 
     -- If the tag has a geometry, assume it is right
     if args.tag then
-        s = args.tag.screen
+        self = args.tag.screen
     end
 
-    s = get_screen(s or capi.mouse.screen)
+    self = get_screen(self or capi.mouse.screen)
 
     local geo = args.bounding_rect or (args.parent and args.parent:geometry()) or
-        s[args.honor_workarea and "workarea" or "geometry"]
+        self[args.honor_workarea and "workarea" or "geometry"]
 
     if (not args.parent) and (not args.bounding_rect) and args.honor_padding then
-        local padding = screen.padding(s)
+        local padding = self.padding
         geo = apply_geometry_ajustments(geo, padding)
     end
 
@@ -271,7 +319,11 @@ end
 capi.screen.add_signal("padding")
 
 -- Extend the luaobject
-object.properties(capi.screen, {auto_emit=true})
+object.properties(capi.screen, {
+    getter_class = screen.object,
+    setter_class = screen.object,
+    auto_emit    = true,
+})
 
 return screen
 

lib/gears/object/properties.lua

@@ -61,7 +61,6 @@ function object.capi_index_fallback(class, args)
         if args.getter_class and args.getter_class[prop] then
             return args.getter_class[prop]
         end
-
         -- In case there is already a "dumb" getter like `awful.tag.getproperty'
         if args.getter_fallback then
             return args.getter_fallback(cobj, prop)

tests/examples/shims/screen.lua

@@ -1,6 +1,6 @@
 local gears_obj = require("gears.object")
 
-local screen = awesome._shim_fake_class()
+local screen, meta = awesome._shim_fake_class()
 
 screen.count = 1
 
@@ -42,8 +42,11 @@ local function create_screen(args)
                     width  = geo.width    - 2*wa,
                     height = geo.height   - 2*wa,
                 }
+            else
+                return meta.__index(_, key)
             end
         end,
+        __new_index = function(...) return meta.__new_index(...) end
     })
 end