doc: Add documentation for the client "window factor" related functions

It might be a good idea to deprecate them and move them to the tag
class. However, these APIs are not exactly well designed, so
moving them wont solve that. Some day the dynamic client layout will
hopefully be merged and send these functions to the heap of smelly
bad ideas trash.

docs/config.ld

@@ -909,6 +909,7 @@ local show_return = {
     ["function"]    = true,
     constructorfct  = true,
     constructorfct2 = true,
+    legacylayout    = true,
     staticfct       = true,
     method          = true,
     deprecated      = true,

lib/awful/client.lua

@@ -1116,11 +1116,14 @@ end
 --- Calculate a client's column number, index in that column, and
 -- number of visible clients in this column.
 --
+-- @DOC_screen_wfact4_EXAMPLE@
+--
 -- @legacylayout awful.client.idx
 -- @tparam client c the client
--- @treturn integer col The column number.
--- @treturn integer idx Index of the client in the column.
--- @treturn integer num The number of visible clients in the column.
+-- @treturn table data A table with "col", "idx" and "num" keys.
+-- @treturn integer data.col The column number.
+-- @treturn integer data.idx Index of the client in the column.
+-- @treturn integer data.num The number of visible clients in the column.
 function client.idx(c)
     c = c or capi.client.focus
     if not c then return end
@@ -1175,12 +1178,22 @@ function client.idx(c)
 end
 
 
---- Set the window factor of a client
+--- Define how tall a client should be in the tile layout.
+--
+-- One valid use case for calling this is restoring serialized layouts.
+-- This function is rather fragile and the behavior may not remain the
+-- same across AwesomeWM versions.
+--
+-- When setting a value, make sure the sum remains 1. Otherwise, the
+-- clients will just go offscreen or get negative size.
+--
+-- @DOC_screen_wfact3_EXAMPLE@
 --
 -- @legacylayout awful.client.setwfact
 -- @tparam number wfact the window factor value
 -- @tparam client c the client
--- @emits property::windowfact
+-- @emits property::windowfact Emitted on the c.first_tag object.
+-- @see tag.master_width_factor
 function client.setwfact(wfact, c)
     -- get the currently selected window
     c = c or capi.client.focus
@@ -1234,6 +1247,12 @@ end
 -- This will emit `property::windowfact` on the specific tag object
 -- `c.screen.selected_tag`.
 --
+-- @DOC_screen_wfact1_EXAMPLE@
+--
+-- Changing the gap will make some clients taller:
+--
+-- @DOC_screen_wfact2_EXAMPLE@
+--
 -- @legacylayout awful.client.incwfact
 -- @tparam number add Amount to increase/decrease the client's window factor by.
 --   Should be between `-current_window_factor` and something close to

objects/client.c

@@ -2981,7 +2981,7 @@ client_kill(client_t *c)
  *   top to bottom).
  * @treturn table A table with clients.
  * @staticfct get
- * @usage for _, c in client.get() do
+ * @usage for _, c in ipairs(client.get()) do
  *     -- do something
  * end
  */

tests/examples/screen/template.lua

@@ -9,6 +9,7 @@ local cairo = require("lgi").cairo
 local Pango = require("lgi").Pango
 local PangoCairo = require("lgi").PangoCairo
 local color = require("gears.color")
+local aclient = require("awful.client")
 
 -- Let the test request a size and file format
 local args = loadfile(file_path)() or 10
@@ -533,6 +534,45 @@ local function draw_mwfact(s)
     cr:translate(tr_x, tr_y)
 end
 
+local function draw_wfact(s)
+    cr:translate(-tr_x, -tr_y)
+
+    local tags = s.selected_tags
+    local windowfacts = s.selected_tag.windowfact
+    local height  = s.tiling_area.height / SCALE_FACTOR
+
+    local sum, gap = 0, s.selected_tag.gap or 0
+
+    for _, t in ipairs(tags) do
+        for _, c in ipairs(t:clients()) do
+            local info = aclient.idx(c)
+            sum = sum + windowfacts[info.col][info.idx]
+        end
+    end
+
+    local offset = s.tiling_area.y * args.factor + tr_y + (2*gap)
+
+    for i = 1, #windowfacts[1] do
+        draw_vruler(
+            s,
+            0, --s.geometry.x + s.geometry.width,
+            s.geometry.width * factor + 5,
+            {
+                y      = math.floor(offset),
+                height =math.ceil( (height/sum) * windowfacts[1][i]),
+                color  = colors.gaps.."66",
+                align  = true,
+            },
+            1
+        )
+
+        offset = offset + (height/sum * windowfacts[1][i]) + (2*gap)
+    end
+
+    cr:translate(tr_x, tr_y)
+end
+
+
 local function draw_client_snap(s)
     cr:translate(-tr_x, -tr_y)
 
@@ -722,7 +762,9 @@ for k=1, screen.count() do
     draw_area(s, s.tiling_area, "tiling_area", (k-1)*10, args.highlight_tiling_area)
 
     -- Draw the ruler.
+    if args.draw_areas ~= false then
         draw_rulers(s)
+    end
 
     -- Draw the wibar.
     for _, wibar in ipairs(args.draw_wibars or {}) do
@@ -781,11 +823,16 @@ for k=1, screen.count() do
         draw_gaps(s)
     end
 
-    -- Draw the useless gaps.
+    -- Draw the master width factor gaps.
     if args.draw_mwfact then
         draw_mwfact(s)
     end
 
+    -- Draw the (rows) width factor.
+    if args.draw_wfact then
+        draw_wfact(s)
+    end
+
     -- Draw the snapping areas of floating clients.
     if args.draw_client_snap then
         draw_client_snap(s)

tests/examples/screen/wfact1.lua

@@ -0,0 +1,61 @@
+--DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_ALL
+
+screen[1]._resize {x = 0, width = 640, height = 480}
+
+
+local awful = {
+    wibar = require("awful.wibar"),
+    tag = require("awful.tag"),
+    tag_layout = require("awful.layout.suit.tile")
+}
+
+function awful.spawn(_, args)
+    local c = client.gen_fake{}
+    c:tags({args.tag})
+    assert(#c:tags() == 1)
+    assert(c:tags()[1] == args.tag)
+end
+
+screen[1].padding = {
+    left   = 40,
+    right  = 40,
+    top    = 20,
+    bottom = 20,
+}
+
+local wibar = awful.wibar {
+    position = "top",
+    height   = 24,
+}
+
+awful.tag.add("1", {
+    screen              = screen[1],
+    selected            = true,
+    layout              = awful.tag_layout.right,
+    gap                 = 5,
+    master_count        = 2,
+    master_width_factor = 0.66
+})
+
+local clients = {
+    ['master #1 \nCol:1, Sum: 2\nRatio: 1/2'] = client.gen_fake{},
+    ['master #2 \nCol:1, Sum: 2\nRatio: 1/2'] = client.gen_fake{},
+    ['slave  #1 \nCol:2, Sum: 3\nRatio: 1/3'] = client.gen_fake{},
+    ['slave  #2 \nCol:2, Sum: 3\nRatio: 1/3'] = client.gen_fake{},
+    ['slave  #3 \nCol:2, Sum: 3\nRatio: 1/3'] = client.gen_fake{}
+}
+
+for _,c in ipairs(clients) do
+    c:tags{"1"}
+end
+
+return {
+    factor                = 2    ,
+    show_boxes            = true,
+    draw_wibars           = {wibar},
+    draw_clients          = clients,
+    display_screen_info   = false,
+    draw_mwfact           = true,
+    draw_wfact            = true,
+    draw_areas            = false,
+}

tests/examples/screen/wfact2.lua

@@ -0,0 +1,83 @@
+--DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_START
+screen[1]._resize {x = 0, width = 640, height = 480}
+
+
+local awful = {
+    client = require("awful.client"),
+    wibar = require("awful.wibar"),
+    tag = require("awful.tag"),
+    tag_layout = require("awful.layout.suit.tile")
+}
+
+function awful.spawn(_, args)
+    local c = client.gen_fake{}
+    c:tags({args.tag})
+    assert(#c:tags() == 1)
+    assert(c:tags()[1] == args.tag)
+end
+
+screen[1].padding = {
+    left   = 40,
+    right  = 40,
+    top    = 20,
+    bottom = 20,
+}
+
+local wibar = awful.wibar {
+    position = "top",
+    height   = 24,
+}
+
+awful.tag.add("1", {
+    screen              = screen[1],
+    selected            = true,
+    layout              = awful.tag_layout.right,
+    gap                 = 5,
+    master_count        = 2,
+    master_width_factor = 0.66
+})
+
+local clients = {
+    ['master #1 \nCol:1, Sum: 2\nRatio: 1/3'] = client.gen_fake{},
+    ['master #2 \nCol:1, Sum: 2\nRatio: 3/4'] = client.gen_fake{},
+    ['slave  #1 \nCol:2, Sum: 3\nRatio: 1/5'] = client.gen_fake{},
+    ['slave  #2 \nCol:2, Sum: 3\nRatio: 3/5'] = client.gen_fake{},
+    ['slave  #3 \nCol:2, Sum: 3\nRatio: 1/5'] = client.gen_fake{}
+}
+
+for _,c in ipairs(clients) do
+    c:tags{"1"}
+end
+
+local tag = screen[1].selected_tag
+
+local param = {
+    tag              = tag,
+    screen           = 1,
+    clients          = tag:clients(),
+    focus            = nil,
+    geometries       = setmetatable({}, {__mode = "k"}),
+    workarea         = tag.screen.workarea,
+    useless_gap      = tag.gaps or 4,
+    apply_size_hints = false,
+}
+
+-- wfact only works after the first arrange call...
+tag.layout.arrange(param)
+
+--DOC_HIDE_END
+
+   awful.client.incwfact(2, client.get()[4])
+   awful.client.incwfact(3, client.get()[2])
+--DOC_HIDE_START
+
+return {
+    factor                = 2    ,
+    show_boxes            = true,
+    draw_wibars           = {wibar},
+    draw_clients          = clients,
+    display_screen_info   = false,
+    draw_mwfact           = true,
+    draw_wfact            = true,
+    draw_areas            = false,
+}

tests/examples/screen/wfact3.lua

@@ -0,0 +1,87 @@
+--DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_START
+screen[1]._resize {x = 0, width = 640, height = 480}
+
+
+local awful = {
+    client = require("awful.client"),
+    wibar = require("awful.wibar"),
+    tag = require("awful.tag"),
+    tag_layout = require("awful.layout.suit.tile")
+}
+
+function awful.spawn(_, args)
+    local c = client.gen_fake{}
+    c:tags({args.tag})
+    assert(#c:tags() == 1)
+    assert(c:tags()[1] == args.tag)
+end
+
+screen[1].padding = {
+    left   = 40,
+    right  = 40,
+    top    = 20,
+    bottom = 20,
+}
+
+local wibar = awful.wibar {
+    position = "top",
+    height   = 24,
+}
+
+awful.tag.add("1", {
+    screen              = screen[1],
+    selected            = true,
+    layout              = awful.tag_layout.right,
+    gap                 = 5,
+    master_count        = 2,
+    master_width_factor = 0.66
+})
+
+local clients = {
+    ['master #1 \nCol:1'] = client.gen_fake{},
+    ['master #2 \nCol:1'] = client.gen_fake{},
+    ['slave  #1 \nCol:2'] = client.gen_fake{},
+    ['slave  #2 \nCol:2'] = client.gen_fake{},
+    ['slave  #3 \nCol:2'] = client.gen_fake{},
+    ['slave  #4 \nCol:2'] = client.gen_fake{}
+}
+
+for _,c in ipairs(clients) do
+    c:tags{"1"}
+end
+
+local tag = screen[1].selected_tag
+
+local param = {
+    tag              = tag,
+    screen           = 1,
+    clients          = tag:clients(),
+    focus            = nil,
+    geometries       = setmetatable({}, {__mode = "k"}),
+    workarea         = tag.screen.workarea,
+    useless_gap      = tag.gaps or 4,
+    apply_size_hints = false,
+}
+
+-- wfact only works after the first arrange call...
+tag.layout.arrange(param)
+
+--DOC_HIDE_END
+   awful.client.setwfact(2/3, client.get()[1])
+   awful.client.setwfact(1/3, client.get()[2])
+   awful.client.setwfact(4/8, client.get()[3])
+   awful.client.setwfact(2/8, client.get()[4])
+   awful.client.setwfact(1/8, client.get()[5])
+   awful.client.setwfact(1/8, client.get()[6])
+--DOC_HIDE_START
+
+return {
+    factor                = 2,
+    show_boxes            = true,
+    draw_wibars           = {wibar},
+    draw_clients          = clients,
+    display_screen_info   = false,
+    draw_mwfact           = true,
+    draw_wfact            = true,
+    draw_areas            = false,
+}

tests/examples/screen/wfact4.lua

@@ -0,0 +1,87 @@
+--DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_START --DOC_GEN_OUTPUT
+
+screen[1]._resize {x = 0, width = 640, height = 480}
+
+
+local awful = {
+    client = require("awful.client"),
+    wibar = require("awful.wibar"),
+    tag = require("awful.tag"),
+    tag_layout = require("awful.layout.suit.tile")
+}
+
+function awful.spawn(_, args)
+    local c = client.gen_fake{}
+    c:tags({args.tag})
+    assert(#c:tags() == 1)
+    assert(c:tags()[1] == args.tag)
+end
+
+screen[1].padding = {
+    left   = 40,
+    right  = 40,
+    top    = 20,
+    bottom = 20,
+}
+
+local wibar = awful.wibar {
+    position = "top",
+    height   = 24,
+}
+
+awful.tag.add("1", {
+    screen              = screen[1],
+    selected            = true,
+    layout              = awful.tag_layout.right,
+    gap                 = 5,
+    master_count        = 2,
+    master_width_factor = 0.66
+})
+
+local clients = {
+    ['master #1 \nCol:1, Sum: 2\nRatio: 1/2'] = client.gen_fake{},
+    ['master #2 \nCol:1, Sum: 2\nRatio: 1/2'] = client.gen_fake{},
+    ['slave  #1 \nCol:2, Sum: 3\nRatio: 1/3'] = client.gen_fake{},
+    ['slave  #2 \nCol:2, Sum: 3\nRatio: 1/3'] = client.gen_fake{},
+    ['slave  #3 \nCol:2, Sum: 3\nRatio: 1/3'] = client.gen_fake{}
+}
+
+for _,c in ipairs(clients) do
+    c:tags{"1"}
+end
+
+local tag = screen[1].selected_tag
+
+local param = {
+    tag              = tag,
+    screen           = 1,
+    clients          = tag:clients(),
+    focus            = nil,
+    geometries       = setmetatable({}, {__mode = "k"}),
+    workarea         = tag.screen.workarea,
+    useless_gap      = tag.gaps or 4,
+    apply_size_hints = false,
+}
+
+-- wfact only works after the first arrange call...
+tag.layout.arrange(param)
+
+--DOC_HIDE_END
+
+   for i, c in ipairs(client.get()) do
+       local data = awful.client.idx(c)
+       print("Client #"..i..":", data.col, data.idx, data.num)
+   end
+
+--DOC_HIDE_START
+
+return {
+    factor                = 2    ,
+    show_boxes            = true,
+    draw_wibars           = {wibar},
+    draw_clients          = clients,
+    display_screen_info   = false,
+    draw_mwfact           = true,
+    draw_wfact            = true,
+    draw_areas            = false,
+}

tests/examples/screen/wfact4.output.txt

@@ -0,0 +1,5 @@
+Client #1:	0	1	2
+Client #2:	0	2	2
+Client #3:	1	1	3
+Client #4:	1	2	3
+Client #5:	1	3	3