From ae711580936fd2bb8ad82e10ce7a4145ff603774 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 17 Oct 2021 19:22:38 -0700 Subject: [PATCH] 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 | 1 + lib/awful/client.lua | 29 +++++++-- objects/client.c | 2 +- tests/examples/screen/template.lua | 51 ++++++++++++++- tests/examples/screen/wfact1.lua | 61 +++++++++++++++++ tests/examples/screen/wfact2.lua | 83 +++++++++++++++++++++++ tests/examples/screen/wfact3.lua | 87 +++++++++++++++++++++++++ tests/examples/screen/wfact4.lua | 87 +++++++++++++++++++++++++ tests/examples/screen/wfact4.output.txt | 5 ++ 9 files changed, 398 insertions(+), 8 deletions(-) create mode 100644 tests/examples/screen/wfact1.lua create mode 100644 tests/examples/screen/wfact2.lua create mode 100644 tests/examples/screen/wfact3.lua create mode 100644 tests/examples/screen/wfact4.lua create mode 100644 tests/examples/screen/wfact4.output.txt diff --git a/docs/config.ld b/docs/config.ld index 99ea11879..e07da6df2 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -909,6 +909,7 @@ local show_return = { ["function"] = true, constructorfct = true, constructorfct2 = true, + legacylayout = true, staticfct = true, method = true, deprecated = true, diff --git a/lib/awful/client.lua b/lib/awful/client.lua index 6b66d8ed7..1f3805402 100644 --- a/lib/awful/client.lua +++ b/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 diff --git a/objects/client.c b/objects/client.c index f8b78e5f5..b9aa45383 100644 --- a/objects/client.c +++ b/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 */ diff --git a/tests/examples/screen/template.lua b/tests/examples/screen/template.lua index 4d6f9ed0c..8fb87009c 100644 --- a/tests/examples/screen/template.lua +++ b/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. - draw_rulers(s) + 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) diff --git a/tests/examples/screen/wfact1.lua b/tests/examples/screen/wfact1.lua new file mode 100644 index 000000000..7760ab2e4 --- /dev/null +++ b/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, +} diff --git a/tests/examples/screen/wfact2.lua b/tests/examples/screen/wfact2.lua new file mode 100644 index 000000000..9c4ffa6d0 --- /dev/null +++ b/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, +} diff --git a/tests/examples/screen/wfact3.lua b/tests/examples/screen/wfact3.lua new file mode 100644 index 000000000..979bb46e7 --- /dev/null +++ b/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, +} diff --git a/tests/examples/screen/wfact4.lua b/tests/examples/screen/wfact4.lua new file mode 100644 index 000000000..fe86268ed --- /dev/null +++ b/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, +} diff --git a/tests/examples/screen/wfact4.output.txt b/tests/examples/screen/wfact4.output.txt new file mode 100644 index 000000000..856685da2 --- /dev/null +++ b/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