From 75764108e1c1e5e6d3227a791118e5e4eaa6e3c7 Mon Sep 17 00:00:00 2001
From: Emmanuel Lepage Vallee <elv1313@gmail.com>
Date: Wed, 20 Apr 2016 21:48:46 -0400
Subject: [PATCH] awful.placement: Make all functions return the geometry

---
 lib/awful/placement.lua                       | 36 +++++++++++++------
 tests/examples/awful/placement/bottom.lua     |  1 +
 .../examples/awful/placement/bottom_left.lua  |  1 +
 .../examples/awful/placement/bottom_right.lua |  1 +
 .../awful/placement/center_horizontal.lua     |  1 +
 tests/examples/awful/placement/centered.lua   |  1 +
 .../awful/placement/closest_mouse.lua         |  2 +-
 tests/examples/awful/placement/left.lua       |  1 +
 tests/examples/awful/placement/right.lua      |  1 +
 .../examples/awful/placement/stretch_down.lua |  1 +
 .../examples/awful/placement/stretch_left.lua |  1 +
 .../awful/placement/stretch_right.lua         |  1 +
 tests/examples/awful/placement/stretch_up.lua |  1 +
 tests/examples/awful/placement/top.lua        |  1 +
 tests/examples/awful/placement/top_left.lua   |  1 +
 tests/examples/awful/placement/top_right.lua  |  1 +
 16 files changed, 41 insertions(+), 11 deletions(-)

diff --git a/lib/awful/placement.lua b/lib/awful/placement.lua
index 4baf67e0d..435d34d08 100644
--- a/lib/awful/placement.lua
+++ b/lib/awful/placement.lua
@@ -476,6 +476,7 @@ end
 -- @tparam[opt=client.focus] drawable d A drawable (like `client`, `mouse`
 --   or `wibox`)
 -- @tparam[opt={}] table args The arguments
+-- @treturn table The new geometry
 -- @treturn string The corner name
 function placement.closest_corner(d, args)
     args = add_context(args, "closest_corner")
@@ -507,9 +508,9 @@ function placement.closest_corner(d, args)
 
     -- Transpose the corner back to the original size
     local new_args = setmetatable({position = corner}, {__index=args})
-    placement_private.align(d, new_args)
+    local ngeo = placement_private.align(d, new_args)
 
-    return corner
+    return ngeo, corner
 end
 
 --- Place the client so no part of it will be outside the screen (workarea).
@@ -551,6 +552,7 @@ end
 --- Place the client where there's place available with minimum overlap.
 --@DOC_awful_placement_no_overlap_EXAMPLE@
 -- @param c The client.
+-- @treturn table The new geometry
 function placement.no_overlap(c)
     c = c or capi.client.focus
     local geometry = area_common(c)
@@ -605,7 +607,7 @@ end
 --- Place the client under the mouse.
 --@DOC_awful_placement_under_mouse_EXAMPLE@
 -- @param c The client.
--- @return The new client geometry.
+-- @treturn table The new geometry
 function placement.under_mouse(c)
     c = c or capi.client.focus
     local c_geometry = area_common(c)
@@ -621,7 +623,7 @@ end
 --@DOC_awful_placement_next_to_mouse_EXAMPLE@
 -- @client[opt=focused] c The client.
 -- @tparam[opt=apply_dpi(5)] integer offset The offset from the mouse position.
--- @return The new client geometry.
+-- @treturn table The new geometry
 function placement.next_to_mouse(c, offset)
     c = c or capi.client.focus
     offset = offset or dpi(5)
@@ -663,6 +665,7 @@ end
 --@DOC_awful_placement_resize_to_mouse_EXAMPLE@
 -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`)
 -- @tparam[opt={}] table args Other arguments
+-- @treturn table The new geometry
 function placement.resize_to_mouse(d, args)
     d    = d or capi.client.focus
     args = add_context(args, "resize_to_mouse")
@@ -675,7 +678,7 @@ function placement.resize_to_mouse(d, args)
     -- To support both growing and shrinking the drawable, it is necessary
     -- to decide to use either "north or south" and "east or west" directions.
     -- Otherwise, the result will always be 1x1
-    local closest_corner = placement.closest_corner(capi.mouse, {
+    local _, closest_corner = placement.closest_corner(capi.mouse, {
         parent        = d,
         include_sides = args.include_sides or false,
     })
@@ -719,6 +722,8 @@ function placement.resize_to_mouse(d, args)
     end
 
     geometry_common(d, args, ngeo)
+
+    return ngeo
 end
 
 --- Move the drawable (client or wibox) `d` to a screen position or side.
@@ -740,6 +745,7 @@ end
 --@DOC_awful_placement_align_EXAMPLE@
 -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`)
 -- @tparam[opt={}] table args Other arguments
+-- @treturn table The new geometry
 function placement.align(d, args)
     args = add_context(args, "align")
     d    = d or capi.client.focus
@@ -757,14 +763,18 @@ function placement.align(d, args)
         dgeo.height
     )
 
-    geometry_common(d, args, {
+    local ngeo = {
         x      = (pos.x and math.ceil(sgeo.x + pos.x) or dgeo.x)       ,
         y      = (pos.y and math.ceil(sgeo.y + pos.y) or dgeo.y)       ,
         width  =            math.ceil(dgeo.width    )            - 2*bw,
         height =            math.ceil(dgeo.height   )            - 2*bw,
-    })
+    }
+
+    geometry_common(d, args, ngeo)
 
     attach(d, placement[args.position], args)
+
+    return ngeo
 end
 
 -- Add the alias functions
@@ -772,7 +782,7 @@ for k in pairs(align_map) do
     placement[k] = function(d, args)
         args = add_context(args, k)
         args.position = k
-        placement_private.align(d, args)
+        return placement_private.align(d, args)
     end
     reverse_align_map[placement[k]] = k
 end
@@ -810,6 +820,7 @@ end
 --@DOC_awful_placement_stretch_EXAMPLE@
 -- @tparam[opt=client.focus] drawable d A drawable (like `client` or `wibox`)
 -- @tparam[opt={}] table args The arguments
+-- @treturn table The new geometry
 function placement.stretch(d, args)
     args = add_context(args, "stretch")
 
@@ -851,6 +862,8 @@ function placement.stretch(d, args)
     geometry_common(d, args, ngeo)
 
     attach(d, placement["stretch_"..args.direction], args)
+
+    return ngeo
 end
 
 -- Add the alias functions
@@ -858,7 +871,7 @@ for _,v in ipairs {"left", "right", "up", "down"} do
     placement["stretch_"..v] =  function(d, args)
         args = add_context(args, "stretch_"..v)
         args.direction = v
-        placement_private.stretch(d, args)
+        return placement_private.stretch(d, args)
     end
 end
 
@@ -879,6 +892,7 @@ end
 --@DOC_awful_placement_maximize_EXAMPLE@
 -- @tparam[opt=client.focus] drawable d A drawable (like `client` or `wibox`)
 -- @tparam[opt={}] table args The arguments
+-- @treturn table The new geometry
 function placement.maximize(d, args)
     args = add_context(args, "maximize")
     d    = d or capi.client.focus
@@ -902,6 +916,8 @@ function placement.maximize(d, args)
     geometry_common(d, args, ngeo)
 
     attach(d, placement.maximize, args)
+
+    return ngeo
 end
 
 -- Add the alias functions
@@ -909,7 +925,7 @@ for _, v in ipairs {"vertically", "horizontally"} do
     placement["maximize_"..v] = function(d2, args)
         args = add_context(args, "maximize_"..v)
         args.axis = v
-        placement_private.maximize(d2, args)
+        return placement_private.maximize(d2, args)
     end
 end
 
diff --git a/tests/examples/awful/placement/bottom.lua b/tests/examples/awful/placement/bottom.lua
index 10dff9ab8..6af09262b 100644
--- a/tests/examples/awful/placement/bottom.lua
+++ b/tests/examples/awful/placement/bottom.lua
@@ -1,6 +1,7 @@
 -- Align a client to the bottom of the parent area. --DOC_HEADER
 -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER
 -- @tparam[opt={}] table args Other arguments") --DOC_HEADER
+-- @treturn table The new geometry --DOC_HEADER
 -- @name bottom --DOC_HEADER
 -- @class function --DOC_HEADER
 
diff --git a/tests/examples/awful/placement/bottom_left.lua b/tests/examples/awful/placement/bottom_left.lua
index a9ebc0629..4d4cff377 100644
--- a/tests/examples/awful/placement/bottom_left.lua
+++ b/tests/examples/awful/placement/bottom_left.lua
@@ -1,6 +1,7 @@
 -- Align a client to the bottom left of the parent area. --DOC_HEADER
 -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER
 -- @tparam[opt={}] table args Other arguments") --DOC_HEADER
+-- @treturn table The new geometry --DOC_HEADER
 -- @name bottom_left --DOC_HEADER
 -- @class function --DOC_HEADER
 
diff --git a/tests/examples/awful/placement/bottom_right.lua b/tests/examples/awful/placement/bottom_right.lua
index 0ad1072e5..2abb44900 100644
--- a/tests/examples/awful/placement/bottom_right.lua
+++ b/tests/examples/awful/placement/bottom_right.lua
@@ -1,6 +1,7 @@
 -- Align a client to the bottom right of the parent area. --DOC_HEADER
 -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER
 -- @tparam[opt={}] table args Other arguments") --DOC_HEADER
+-- @treturn table The new geometry --DOC_HEADER
 -- @name bottom_right --DOC_HEADER
 -- @class function --DOC_HEADER
 
diff --git a/tests/examples/awful/placement/center_horizontal.lua b/tests/examples/awful/placement/center_horizontal.lua
index b9d1d6bb0..931b947c1 100644
--- a/tests/examples/awful/placement/center_horizontal.lua
+++ b/tests/examples/awful/placement/center_horizontal.lua
@@ -1,6 +1,7 @@
 -- Align a client to the horizontal center left of the parent area. --DOC_HEADER
 -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER
 -- @tparam[opt={}] table args Other arguments") --DOC_HEADER
+-- @treturn table The new geometry --DOC_HEADER
 -- @name center_horizontal --DOC_HEADER
 -- @class function --DOC_HEADER
 screen[1]._resize {width = 128, height = 96} --DOC_HIDE
diff --git a/tests/examples/awful/placement/centered.lua b/tests/examples/awful/placement/centered.lua
index af1a1c84b..d6b1e3aec 100644
--- a/tests/examples/awful/placement/centered.lua
+++ b/tests/examples/awful/placement/centered.lua
@@ -1,6 +1,7 @@
 -- Align a client to the center of the parent area. --DOC_HEADER
 -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER
 -- @tparam[opt={}] table args Other arguments") --DOC_HEADER
+-- @treturn table The new geometry --DOC_HEADER
 -- @name centered --DOC_HEADER
 -- @class function --DOC_HEADER
 
diff --git a/tests/examples/awful/placement/closest_mouse.lua b/tests/examples/awful/placement/closest_mouse.lua
index 906426415..4269d1d8b 100644
--- a/tests/examples/awful/placement/closest_mouse.lua
+++ b/tests/examples/awful/placement/closest_mouse.lua
@@ -55,7 +55,7 @@ assert(mouse.coords().x == c.x and mouse.coords().y == c.y+c.height+2*bw) --DOC_
  
  -- It is possible to emulate the mouse API to get the closest corner of
  -- random area
-local corner = awful.placement.closest_corner(
+local _, corner = awful.placement.closest_corner(
     {coords=function() return {x = 100, y=100} end},
     {include_sides = true, bounding_rect = {x=0, y=0, width=200, height=200}}
 )
diff --git a/tests/examples/awful/placement/left.lua b/tests/examples/awful/placement/left.lua
index 49cf93ac4..d3e4e6981 100644
--- a/tests/examples/awful/placement/left.lua
+++ b/tests/examples/awful/placement/left.lua
@@ -1,6 +1,7 @@
 -- Align a client to the left of the parent area. --DOC_HEADER
 -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER
 -- @tparam[opt={}] table args Other arguments") --DOC_HEADER
+-- @treturn table The new geometry --DOC_HEADER
 -- @name left --DOC_HEADER
 -- @class function --DOC_HEADER
 
diff --git a/tests/examples/awful/placement/right.lua b/tests/examples/awful/placement/right.lua
index d24501161..4e16cea6c 100644
--- a/tests/examples/awful/placement/right.lua
+++ b/tests/examples/awful/placement/right.lua
@@ -1,6 +1,7 @@
 -- Align a client to the right of the parent area. --DOC_HEADER
 -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER
 -- @tparam[opt={}] table args Other arguments") --DOC_HEADER
+-- @treturn table The new geometry --DOC_HEADER
 -- @name right --DOC_HEADER
 -- @class function --DOC_HEADER
 
diff --git a/tests/examples/awful/placement/stretch_down.lua b/tests/examples/awful/placement/stretch_down.lua
index 258647f8a..720da36d6 100644
--- a/tests/examples/awful/placement/stretch_down.lua
+++ b/tests/examples/awful/placement/stretch_down.lua
@@ -1,6 +1,7 @@
 -- Stretch the drawable to the bottom of the parent area. --DOC_HEADER
 -- @tparam drawable d A drawable (like `client` or `wibox`) --DOC_HEADER
 -- @tparam[opt={}] table args Other arguments --DOC_HEADER
+-- @treturn table The new geometry --DOC_HEADER
 -- @name stretch_down --DOC_HEADER
 -- @class function --DOC_HEADER
 
diff --git a/tests/examples/awful/placement/stretch_left.lua b/tests/examples/awful/placement/stretch_left.lua
index 51364697f..4fdd58579 100644
--- a/tests/examples/awful/placement/stretch_left.lua
+++ b/tests/examples/awful/placement/stretch_left.lua
@@ -1,6 +1,7 @@
 -- Stretch the drawable to the left of the parent area. --DOC_HEADER
 -- @tparam drawable d A drawable (like `client` or `wibox`) --DOC_HEADER
 -- @tparam[opt={}] table args Other arguments --DOC_HEADER
+-- @treturn table The new geometry --DOC_HEADER
 -- @name stretch_left --DOC_HEADER
 -- @class function --DOC_HEADER
 
diff --git a/tests/examples/awful/placement/stretch_right.lua b/tests/examples/awful/placement/stretch_right.lua
index 9965d1a61..47dcce807 100644
--- a/tests/examples/awful/placement/stretch_right.lua
+++ b/tests/examples/awful/placement/stretch_right.lua
@@ -1,6 +1,7 @@
 -- Stretch the drawable to the right of the parent area. --DOC_HEADER
 -- @tparam drawable d A drawable (like `client` or `wibox`) --DOC_HEADER
 -- @tparam[opt={}] table args Other arguments --DOC_HEADER
+-- @treturn table The new geometry --DOC_HEADER
 -- @name stretch_right --DOC_HEADER
 -- @class function --DOC_HEADER
 
diff --git a/tests/examples/awful/placement/stretch_up.lua b/tests/examples/awful/placement/stretch_up.lua
index 817a11d5e..0ccfd2bcc 100644
--- a/tests/examples/awful/placement/stretch_up.lua
+++ b/tests/examples/awful/placement/stretch_up.lua
@@ -1,6 +1,7 @@
 -- Stretch the drawable to the top of the parent area. --DOC_HEADER
 -- @tparam drawable d A drawable (like `client` or `wibox`) --DOC_HEADER
 -- @tparam[opt={}] table args Other arguments --DOC_HEADER
+-- @treturn table The new geometry --DOC_HEADER
 -- @name stretch_up --DOC_HEADER
 -- @class function --DOC_HEADER
 
diff --git a/tests/examples/awful/placement/top.lua b/tests/examples/awful/placement/top.lua
index f84ea3066..b3375fbcb 100644
--- a/tests/examples/awful/placement/top.lua
+++ b/tests/examples/awful/placement/top.lua
@@ -1,6 +1,7 @@
 -- Align a client to the top of the parent area. --DOC_HEADER
 -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER
 -- @tparam[opt={}] table args Other arguments") --DOC_HEADER
+-- @treturn table The new geometry --DOC_HEADER
 -- @name top --DOC_HEADER
 -- @class function --DOC_HEADER
 
diff --git a/tests/examples/awful/placement/top_left.lua b/tests/examples/awful/placement/top_left.lua
index a2bb3b586..f70b85f60 100644
--- a/tests/examples/awful/placement/top_left.lua
+++ b/tests/examples/awful/placement/top_left.lua
@@ -1,6 +1,7 @@
 -- Align a client to the top left of the parent area. --DOC_HEADER
 -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER
 -- @tparam[opt={}] table args Other arguments") --DOC_HEADER
+-- @treturn table The new geometry --DOC_HEADER
 -- @name top_left --DOC_HEADER
 -- @class function --DOC_HEADER
 
diff --git a/tests/examples/awful/placement/top_right.lua b/tests/examples/awful/placement/top_right.lua
index a94890c98..ef6fc8338 100644
--- a/tests/examples/awful/placement/top_right.lua
+++ b/tests/examples/awful/placement/top_right.lua
@@ -1,6 +1,7 @@
 -- Align a client to the top right of the parent area. --DOC_HEADER
 -- @tparam drawable d A drawable (like `client`, `mouse` or `wibox`) --DOC_HEADER
 -- @tparam[opt={}] table args Other arguments") --DOC_HEADER
+-- @treturn table The new geometry --DOC_HEADER
 -- @name top_right --DOC_HEADER
 -- @class function --DOC_HEADER