From 80515c2225e21016dc7cc51e154552a0ade163b0 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Fri, 15 Oct 2021 14:27:30 -0700 Subject: [PATCH 01/18] doc: Fix rendering of `client:swap()`. --- objects/client.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/objects/client.c b/objects/client.c index 36db11c3f..5a47779fa 100644 --- a/objects/client.c +++ b/objects/client.c @@ -3090,8 +3090,8 @@ luaA_client_kill(lua_State *L) * @tparam client c A client to swap with. * @method swap * @emits swapped - * @emitstparam swapped client The other client. - * @emitstparam swapped boolean `true` when `:swap()` was called + * @emitstparam swapped client other The other client. + * @emitstparam swapped boolean is_origin `true` when `:swap()` was called * on *self* rather than the other client. `false` when * `:swap()` was called on the other client. * @emits list From 206bc7e5de156a13be0968644b6256258942488b Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Fri, 15 Oct 2021 17:45:12 -0700 Subject: [PATCH 02/18] doc: Fix client.border_color example rendering. --- tests/examples/awful/client/border_width.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/examples/awful/client/border_width.lua b/tests/examples/awful/client/border_width.lua index 0997f68ff..980c9e8c7 100644 --- a/tests/examples/awful/client/border_width.lua +++ b/tests/examples/awful/client/border_width.lua @@ -1,7 +1,7 @@ --DOC_NO_USAGE --DOC_GEN_IMAGE --DOC_ASTERISK local awful = require("awful") --DOC_HIDE local wibox = require("wibox") --DOC_HIDE -local beautiful = require("beautiful") +local beautiful = require("beautiful") --DOC_HIDE screen[1]._resize {width = 480, height = 200} --DOC_HIDE From 203d0638be2d75e48ec9e81c54a1e72d5701dbeb Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Fri, 15 Oct 2021 19:42:48 -0700 Subject: [PATCH 03/18] background: Improve the fallback rendering accuracy. While it has a little aliasing problem, it actually correctly renders the border using a mask like the normal code path. --- lib/wibox/container/background.lua | 45 +++++++++++++++++++++--------- 1 file changed, 32 insertions(+), 13 deletions(-) diff --git a/lib/wibox/container/background.lua b/lib/wibox/container/background.lua index 05d4b42cc..a93a93ac9 100644 --- a/lib/wibox/container/background.lua +++ b/lib/wibox/container/background.lua @@ -39,14 +39,6 @@ function background._use_fallback_algorithm() shape(cr, width, height) - if bw > 0 then - cr:save() --Save to avoid messing with the original source - cr:set_line_width(bw) - cr:set_source(color(self._private.shape_border_color or self._private.foreground or beautiful.fg_normal)) - cr:stroke_preserve() - cr:restore() - end - if self._private.background then cr:save() --Save to avoid messing with the original source cr:set_source(self._private.background) @@ -61,18 +53,45 @@ function background._use_fallback_algorithm() cr:set_source(self._private.foreground) end end + background.after_draw_children = function(self, _, cr, width, height) local bw = self._private.shape_border_width or 0 local shape = self._private.shape or gshape.rectangle if bw > 0 then cr:save() - cr:translate(bw, bw) - width, height = width - 2*bw, height - 2*bw - shape(cr, width, height) - cr:set_line_width(bw) + cr:reset_clip() + + local mat = cr:get_matrix() + + -- Prevent the inner part of the border from being written. + local mask = cairo.RecordingSurface(cairo.Content.COLOR_ALPHA, + cairo.Rectangle { x = 0, y = 0, width = mat.x0 + width, height = mat.y0 + height }) + + local mask_cr = cairo.Context(mask) + mask_cr:translate(mat.x0, mat.y0) + + -- Clear the surface. + mask_cr:set_operator(cairo.Operator.CLEAR) + mask_cr:set_source_rgba(0, 1, 0, 0) + mask_cr:paint() + + -- Paint the inner and outer borders. + mask_cr:set_operator(cairo.Operator.SOURCE) + mask_cr:translate(bw, bw) + mask_cr:set_source_rgba(1, 0, 0, 1) + mask_cr:set_line_width(2*bw) + shape(mask_cr, width - 2*bw, height - 2*bw) + mask_cr:stroke_preserve() + + -- Remove the inner part. + mask_cr:set_source_rgba(0, 1, 0, 0) + mask_cr:set_operator(cairo.Operator.CLEAR) + mask_cr:fill() + mask:flush() + cr:set_source(color(self._private.shape_border_color or self._private.foreground or beautiful.fg_normal)) - cr:stroke() + cr:mask_surface(mask, 0,0) cr:restore() end end From c1d25cd70d37d2768bc51e623396985e6a3d4740 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Fri, 15 Oct 2021 19:43:58 -0700 Subject: [PATCH 04/18] doc: Improve the `awful` template client widget. It was incorrectly sized. --- tests/examples/awful/template.lua | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/tests/examples/awful/template.lua b/tests/examples/awful/template.lua index 1a20a8b39..4db97c3ac 100644 --- a/tests/examples/awful/template.lua +++ b/tests/examples/awful/template.lua @@ -156,12 +156,13 @@ local function client_widget(c, col, label) }, layout = wibox.layout.stack }, - border_width = bw, - border_color = bc, - shape_clip = true, - fg = beautiful.fg_normal or "#000000", - bg = col, - shape = function(cr2, w, h) + border_width = bw, + border_color = bc, + shape_clip = true, + border_strategy = "inner", + fg = beautiful.fg_normal or "#000000", + bg = col, + shape = function(cr2, w, h) return shape.rounded_rect(cr2, w, h, args.radius or 5) end, From 028d01590a9e295728004463202d6c036c636346 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Fri, 15 Oct 2021 19:50:03 -0700 Subject: [PATCH 05/18] doc: Add a client.border_width example. --- objects/client.c | 14 +- tests/examples/awful/client/border_color.lua | 85 +++++++++++ tests/examples/awful/client/border_width.lua | 150 ++++++++++--------- 3 files changed, 178 insertions(+), 71 deletions(-) create mode 100644 tests/examples/awful/client/border_color.lua diff --git a/objects/client.c b/objects/client.c index 5a47779fa..19ad5f3f5 100644 --- a/objects/client.c +++ b/objects/client.c @@ -727,6 +727,15 @@ lua_class_t client_class; /** * The client border width. * + * When manually set (for example, in `ruled.client` rules), this value + * will be static. Otherwise, it is controlled by many `beautiful` variables. + * + * Be careful, the borders are **around** the geometry, not part of it. If + * you want more fancy border, use the `awful.titlebar` API to create + * titlebars on each side of the client. + * + * @DOC_awful_client_border_width_EXAMPLE@ + * * @property border_width * @tparam integer border_width * @propemits false false @@ -759,7 +768,7 @@ lua_class_t client_class; /** * The client border color. * - * @DOC_awful_client_border_width_EXAMPLE@ + * @DOC_awful_client_border_color_EXAMPLE@ * * Note that setting this directly will override and disable all related theme * variables. @@ -3087,6 +3096,9 @@ luaA_client_kill(lua_State *L) } /** Swap a client with another one in global client list. + * + * @DOC_sequences_client_swap1_EXAMPLE@ + * * @tparam client c A client to swap with. * @method swap * @emits swapped diff --git a/tests/examples/awful/client/border_color.lua b/tests/examples/awful/client/border_color.lua new file mode 100644 index 000000000..980c9e8c7 --- /dev/null +++ b/tests/examples/awful/client/border_color.lua @@ -0,0 +1,85 @@ +--DOC_NO_USAGE --DOC_GEN_IMAGE --DOC_ASTERISK +local awful = require("awful") --DOC_HIDE +local wibox = require("wibox") --DOC_HIDE +local beautiful = require("beautiful") --DOC_HIDE + +screen[1]._resize {width = 480, height = 200} --DOC_HIDE + +local wb = awful.wibar { position = "top" }--DOC_HIDE + +--DOC_HIDE Create the same number of tags as the default config +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.layouts[1]) --DOC_HIDE + +--DOC_HIDE Only bother with widgets that are visible by default +local mykeyboardlayout = awful.widget.keyboardlayout() --DOC_HIDE +local mytextclock = wibox.widget.textclock() --DOC_HIDE +local mytaglist = awful.widget.taglist(screen[1], awful.widget.taglist.filter.all, {}) --DOC_HIDE +local mytasklist = awful.widget.tasklist(screen[1], awful.widget.tasklist.filter.currenttags, {}) --DOC_HIDE + +client.connect_signal("request::titlebars", function(c)--DOC_HIDE + local top_titlebar = awful.titlebar(c, {--DOC_HIDE + height = 20,--DOC_HIDE + bg_normal = beautiful.bg_normal,--DOC_HIDE + })--DOC_HIDE + + top_titlebar : setup {--DOC_HIDE + { -- Left--DOC_HIDE + awful.titlebar.widget.iconwidget(c),--DOC_HIDE + layout = wibox.layout.fixed.horizontal--DOC_HIDE + },--DOC_HIDE + { -- Middle--DOC_HIDE + { -- Title--DOC_HIDE + align = "center",--DOC_HIDE + widget = awful.titlebar.widget.titlewidget(c)--DOC_HIDE + },--DOC_HIDE + layout = wibox.layout.flex.horizontal--DOC_HIDE + },--DOC_HIDE + { -- Right--DOC_HIDE + awful.titlebar.widget.floatingbutton (c),--DOC_HIDE + awful.titlebar.widget.maximizedbutton(c),--DOC_HIDE + awful.titlebar.widget.stickybutton (c),--DOC_HIDE + awful.titlebar.widget.ontopbutton (c),--DOC_HIDE + awful.titlebar.widget.closebutton (c),--DOC_HIDE + layout = wibox.layout.fixed.horizontal()--DOC_HIDE + },--DOC_HIDE + layout = wibox.layout.align.horizontal--DOC_HIDE + }--DOC_HIDE +end)--DOC_HIDE + + +wb:setup { --DOC_HIDE + layout = wibox.layout.align.horizontal, --DOC_HIDE + { --DOC_HIDE + mytaglist, --DOC_HIDE + layout = wibox.layout.fixed.horizontal, --DOC_HIDE + }, --DOC_HIDE + mytasklist, --DOC_HIDE + { --DOC_HIDE + layout = wibox.layout.fixed.horizontal, --DOC_HIDE + mykeyboardlayout, --DOC_HIDE + mytextclock, --DOC_HIDE + }, --DOC_HIDE +} --DOC_HIDE + +require("gears.timer").run_delayed_calls_now()--DOC_HIDE + +local function gen_client(label)--DOC_HIDE + local c = client.gen_fake {hide_first=true} --DOC_HIDE + + c:geometry {--DOC_HIDE + x = 105,--DOC_HIDE + y = 60,--DOC_HIDE + height = 60,--DOC_HIDE + width = 230,--DOC_HIDE + }--DOC_HIDE + c._old_geo = {c:geometry()} --DOC_HIDE + c:set_label(label) --DOC_HIDE + c:emit_signal("request::titlebars")--DOC_HIDE + return c --DOC_HIDE +end --DOC_HIDE + + local c = gen_client("A manually set border_color") --DOC_HIDE + c.border_color = "#ff00ff" + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 + diff --git a/tests/examples/awful/client/border_width.lua b/tests/examples/awful/client/border_width.lua index 980c9e8c7..a711d6d59 100644 --- a/tests/examples/awful/client/border_width.lua +++ b/tests/examples/awful/client/border_width.lua @@ -1,85 +1,95 @@ ---DOC_NO_USAGE --DOC_GEN_IMAGE --DOC_ASTERISK -local awful = require("awful") --DOC_HIDE -local wibox = require("wibox") --DOC_HIDE -local beautiful = require("beautiful") --DOC_HIDE +--DOC_NO_USAGE --DOC_GEN_IMAGE --DOC_ASTERISK --DOC_HIDE_START +local awful = require("awful") +local wibox = require("wibox") +local beautiful = require("beautiful") -screen[1]._resize {width = 480, height = 200} --DOC_HIDE +screen[1]._resize {width = 480, height = 200} -local wb = awful.wibar { position = "top" }--DOC_HIDE +local wb = awful.wibar { position = "top" } ---DOC_HIDE Create the same number of tags as the default config -awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.layouts[1]) --DOC_HIDE +-- Create the same number of tags as the default config +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.layouts[1]) ---DOC_HIDE Only bother with widgets that are visible by default -local mykeyboardlayout = awful.widget.keyboardlayout() --DOC_HIDE -local mytextclock = wibox.widget.textclock() --DOC_HIDE -local mytaglist = awful.widget.taglist(screen[1], awful.widget.taglist.filter.all, {}) --DOC_HIDE -local mytasklist = awful.widget.tasklist(screen[1], awful.widget.tasklist.filter.currenttags, {}) --DOC_HIDE +-- Only bother with widgets that are visible by default +local mykeyboardlayout = awful.widget.keyboardlayout() +local mytextclock = wibox.widget.textclock() +local mytaglist = awful.widget.taglist(screen[1], awful.widget.taglist.filter.all, {}) +local mytasklist = awful.widget.tasklist(screen[1], awful.widget.tasklist.filter.currenttags, {}) -client.connect_signal("request::titlebars", function(c)--DOC_HIDE - local top_titlebar = awful.titlebar(c, {--DOC_HIDE - height = 20,--DOC_HIDE - bg_normal = beautiful.bg_normal,--DOC_HIDE - })--DOC_HIDE +client.connect_signal("request::titlebars", function(c) + local top_titlebar = awful.titlebar(c, { + height = 20, + bg_normal = beautiful.bg_normal, + }) - top_titlebar : setup {--DOC_HIDE - { -- Left--DOC_HIDE - awful.titlebar.widget.iconwidget(c),--DOC_HIDE - layout = wibox.layout.fixed.horizontal--DOC_HIDE - },--DOC_HIDE - { -- Middle--DOC_HIDE - { -- Title--DOC_HIDE - align = "center",--DOC_HIDE - widget = awful.titlebar.widget.titlewidget(c)--DOC_HIDE - },--DOC_HIDE - layout = wibox.layout.flex.horizontal--DOC_HIDE - },--DOC_HIDE - { -- Right--DOC_HIDE - awful.titlebar.widget.floatingbutton (c),--DOC_HIDE - awful.titlebar.widget.maximizedbutton(c),--DOC_HIDE - awful.titlebar.widget.stickybutton (c),--DOC_HIDE - awful.titlebar.widget.ontopbutton (c),--DOC_HIDE - awful.titlebar.widget.closebutton (c),--DOC_HIDE - layout = wibox.layout.fixed.horizontal()--DOC_HIDE - },--DOC_HIDE - layout = wibox.layout.align.horizontal--DOC_HIDE - }--DOC_HIDE -end)--DOC_HIDE + top_titlebar : setup { + { -- Left + awful.titlebar.widget.iconwidget(c), + layout = wibox.layout.fixed.horizontal + }, + { -- Middle + { -- Title + align = "center", + widget = awful.titlebar.widget.titlewidget(c) + }, + layout = wibox.layout.flex.horizontal + }, + { -- Right + awful.titlebar.widget.floatingbutton (c), + awful.titlebar.widget.maximizedbutton(c), + awful.titlebar.widget.stickybutton (c), + awful.titlebar.widget.ontopbutton (c), + awful.titlebar.widget.closebutton (c), + layout = wibox.layout.fixed.horizontal() + }, + layout = wibox.layout.align.horizontal + } +end) -wb:setup { --DOC_HIDE - layout = wibox.layout.align.horizontal, --DOC_HIDE - { --DOC_HIDE - mytaglist, --DOC_HIDE - layout = wibox.layout.fixed.horizontal, --DOC_HIDE - }, --DOC_HIDE - mytasklist, --DOC_HIDE - { --DOC_HIDE - layout = wibox.layout.fixed.horizontal, --DOC_HIDE - mykeyboardlayout, --DOC_HIDE - mytextclock, --DOC_HIDE - }, --DOC_HIDE -} --DOC_HIDE +wb:setup { + layout = wibox.layout.align.horizontal, + { + mytaglist, + layout = wibox.layout.fixed.horizontal, + }, + mytasklist, + { + layout = wibox.layout.fixed.horizontal, + mykeyboardlayout, + mytextclock, + }, +} -require("gears.timer").run_delayed_calls_now()--DOC_HIDE +require("gears.timer").run_delayed_calls_now() +local counter = 0 -local function gen_client(label)--DOC_HIDE - local c = client.gen_fake {hide_first=true} --DOC_HIDE +local function gen_client(label) + local c = client.gen_fake {hide_first=true} - c:geometry {--DOC_HIDE - x = 105,--DOC_HIDE - y = 60,--DOC_HIDE - height = 60,--DOC_HIDE - width = 230,--DOC_HIDE - }--DOC_HIDE - c._old_geo = {c:geometry()} --DOC_HIDE - c:set_label(label) --DOC_HIDE - c:emit_signal("request::titlebars")--DOC_HIDE - return c --DOC_HIDE -end --DOC_HIDE + c:geometry { + x = 45 + counter*1.75, + y = 30 + counter, + height = 60, + width = 230, + } + c._old_geo = {c:geometry()} + c:set_label(label) + c:emit_signal("request::titlebars") + c.border_color = beautiful.bg_highlight + counter = counter + 40 - local c = gen_client("A manually set border_color") --DOC_HIDE - c.border_color = "#ff00ff" + return c +end + + local c1 = gen_client("Border width: 0") + local c2 = gen_client("Border width: 2") + local c3 = gen_client("Border width: 10") +--DOC_HIDE_END + + c1.border_width = 0 + c2.border_width = 2 + c3.border_width = 10 --DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 From e40ad11ec0ba6c4b5bac08da0bdfd5beb90b2122 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Fri, 15 Oct 2021 19:50:22 -0700 Subject: [PATCH 06/18] shims: Implement client:swap(). --- tests/examples/shims/client.lua | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/tests/examples/shims/client.lua b/tests/examples/shims/client.lua index f816016be..208fe7c26 100644 --- a/tests/examples/shims/client.lua +++ b/tests/examples/shims/client.lua @@ -192,6 +192,24 @@ function client.gen_fake(args) assert(not ret.valid) end + function ret:swap(other) + local idx1, idx2 = nil, nil + for k, c in ipairs(clients) do + if c == ret then + idx1 = k + elseif c == other then + idx2 = k + end + end + + if not (idx1 and idx2) then return end + + clients[idx1], clients[idx2] = other, ret + ret:emit_signal("swapped", other, true) + other:emit_signal("swapped", ret, false) + client.emit_signal("list") + end + titlebar_meta(ret) function ret:tags(new) --FIXME From 785ca98337c746b87fc7bf5fa35242d25e6e7cae Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Fri, 15 Oct 2021 19:57:11 -0700 Subject: [PATCH 07/18] client: Turn client.setslave/setmaster into properties. It also no longer use the master/slave name. In this case, it kinds of make sense since, for example, of the tag `master_count` is greater than the number of clients, calling `client.setslave` move the client to another "master" slot. Closes #626 --- lib/awful/client.lua | 49 ++++++++++++++++++++++++++++++++++++-------- 1 file changed, 40 insertions(+), 9 deletions(-) diff --git a/lib/awful/client.lua b/lib/awful/client.lua index d80ea52df..44b2107a5 100644 --- a/lib/awful/client.lua +++ b/lib/awful/client.lua @@ -428,7 +428,7 @@ end --- Get the master window. -- --- @legacylayout awful.client.getmaster +-- @deprecated awful.client.getmaster -- @tparam[opt=awful.screen.focused()] screen s The screen. -- @treturn client The master client. function client.getmaster(s) @@ -438,22 +438,53 @@ end --- Set the client as master: put it at the beginning of other windows. -- --- @legacylayout awful.client.setmaster +-- @deprecated awful.client.setmaster -- @tparam client c The window to set as master. function client.setmaster(c) - local cls = gtable.reverse(capi.client.get(c.screen)) - for _, v in pairs(cls) do - c:swap(v) - end + c:to_primary_section() end --- Set the client as slave: put it at the end of other windows. --- @legacylayout awful.client.setslave +-- @deprecated awful.client.setslave -- @tparam client c The window to set as slave. function client.setslave(c) - local cls = capi.client.get(c.screen) + c:to_secondary_section() +end + +--- Move the client to the most significant layout position. +-- +-- This only affects tiled clients. It will shift all other +-- client to fill the gap caused to by the move. +-- +-- @DOC_sequences_client_to_primary_EXAMPLE@ +-- +-- @method to_primary_section +-- @see swap +-- @see to_secondary_section +function client.object:to_primary_section() + local cls = gtable.reverse(capi.client.get(self.screen)) + for _, v in pairs(cls) do - c:swap(v) + self:swap(v) + end +end + +--- Move the client to the least significant layout position. +-- +-- This only affects tiled clients. It will shift all other +-- client to fill the gap caused to by the move. +-- +-- @DOC_sequences_client_to_secondary_EXAMPLE@ +-- +-- @method to_secondary_section +-- @see swap +-- @see to_primary_section + +function client.object:to_secondary_section() + local cls = capi.client.get(self.screen) + + for _, v in pairs(cls) do + self:swap(v) end end From 667a0dfc1833eafc6e37470ad683ff52a992aa69 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Fri, 15 Oct 2021 19:59:24 -0700 Subject: [PATCH 08/18] tests: Add tests for swapping a client. --- tests/examples/sequences/client/swap1.lua | 41 +++++++++++++++++++ .../examples/sequences/client/to_primary.lua | 41 +++++++++++++++++++ .../sequences/client/to_secondary.lua | 41 +++++++++++++++++++ 3 files changed, 123 insertions(+) create mode 100644 tests/examples/sequences/client/swap1.lua create mode 100644 tests/examples/sequences/client/to_primary.lua create mode 100644 tests/examples/sequences/client/to_secondary.lua diff --git a/tests/examples/sequences/client/swap1.lua b/tests/examples/sequences/client/swap1.lua new file mode 100644 index 000000000..c82c1688f --- /dev/null +++ b/tests/examples/sequences/client/swap1.lua @@ -0,0 +1,41 @@ + --DOC_GEN_IMAGE --DOC_ASTERISK +local module = ... --DOC_HIDE +require("ruled.client") --DOC_HIDE +local awful = {tag = require("awful.tag"), layout = require("awful.layout")} --DOC_HIDE +awful.placement = require("awful.placement") --DOC_HIDE +require("awful.ewmh") --DOC_HIDE +screen[1]:fake_resize(0, 0, 800, 480) --DOC_HIDE +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.suit.tile) --DOC_HIDE + +function awful.spawn(name) --DOC_HIDE + client.gen_fake{class = name, name = name, x = 2094, y=10, width = 60, height =50, screen=screen[1]} --DOC_HIDE +end --DOC_HIDE + + +--DOC_NEWLINE + +module.add_event("Spawn 5 clients in a `awful.layout.suit.tile` layout.", function() --DOC_HIDE + -- Spawn 5 clients. + for i=1, 5 do + awful.spawn("Client #"..i) + end + + --DOC_NEWLINE + + client.get()[2]:activate {} + client.get()[2].color = "#ff777733" --DOC_HIDE +end) --DOC_HIDE + +--DOC_NEWLINE +module.display_tags() --DOC_HIDE + +module.add_event("Call `:swap()` on the second client.", function() --DOC_HIDE + client.get()[2]:swap(client.get()[4]) +end) --DOC_HIDE + +module.display_tags() --DOC_HIDE + +module.execute { display_screen = true , display_clients = true, --DOC_HIDE + display_label = false, display_client_name = true, --DOC_HIDE + display_mouse = true , --DOC_HIDE +} --DOC_HIDE diff --git a/tests/examples/sequences/client/to_primary.lua b/tests/examples/sequences/client/to_primary.lua new file mode 100644 index 000000000..28fb561a1 --- /dev/null +++ b/tests/examples/sequences/client/to_primary.lua @@ -0,0 +1,41 @@ + --DOC_GEN_IMAGE +local module = ... --DOC_HIDE +require("ruled.client") --DOC_HIDE +local awful = {tag = require("awful.tag"), layout = require("awful.layout")} --DOC_HIDE +awful.placement = require("awful.placement") --DOC_HIDE +require("awful.ewmh") --DOC_HIDE +screen[1]:fake_resize(0, 0, 800, 480) --DOC_HIDE +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.suit.tile) --DOC_HIDE + +function awful.spawn(name) --DOC_HIDE + client.gen_fake{class = name, name = name, x = 2094, y=10, width = 60, height =50, screen=screen[1]} --DOC_HIDE +end --DOC_HIDE + + +--DOC_NEWLINE + +module.add_event("Spawn 5 clients in a `awful.layout.suit.tile` layout.", function() --DOC_HIDE + -- Spawn a client on screen #3 + for i=1, 5 do + awful.spawn("Client #"..i) + end + + --DOC_NEWLINE + + client.get()[5]:activate {} + client.get()[5].color = "#ff777733" --DOC_HIDE +end) --DOC_HIDE + +--DOC_NEWLINE +module.display_tags() --DOC_HIDE + +module.add_event("Call `:to_primary_section()` on the 5th client.", function() --DOC_HIDE + client.get()[5]:to_primary_section() +end) --DOC_HIDE + +module.display_tags() --DOC_HIDE + +module.execute { display_screen = true , display_clients = true, --DOC_HIDE + display_label = false, display_client_name = true, --DOC_HIDE + display_mouse = true , --DOC_HIDE +} --DOC_HIDE diff --git a/tests/examples/sequences/client/to_secondary.lua b/tests/examples/sequences/client/to_secondary.lua new file mode 100644 index 000000000..b691aee37 --- /dev/null +++ b/tests/examples/sequences/client/to_secondary.lua @@ -0,0 +1,41 @@ + --DOC_GEN_IMAGE +local module = ... --DOC_HIDE +require("ruled.client") --DOC_HIDE +local awful = {tag = require("awful.tag"), layout = require("awful.layout")} --DOC_HIDE +awful.placement = require("awful.placement") --DOC_HIDE +require("awful.ewmh") --DOC_HIDE +screen[1]:fake_resize(0, 0, 800, 480) --DOC_HIDE +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.suit.tile) --DOC_HIDE + +function awful.spawn(name) --DOC_HIDE + client.gen_fake{class = name, name = name, x = 2094, y=10, width = 60, height =50, screen=screen[1]} --DOC_HIDE +end --DOC_HIDE + + +--DOC_NEWLINE + +module.add_event("Spawn 5 clients in a `awful.layout.suit.tile` layout.", function() --DOC_HIDE + -- Spawn a client on screen #3 + for i=1, 5 do + awful.spawn("Client #"..i) + end + + --DOC_NEWLINE + + client.get()[1]:activate {} + client.get()[1].color = "#ff777733" --DOC_HIDE +end) --DOC_HIDE + +--DOC_NEWLINE +module.display_tags() --DOC_HIDE + +module.add_event("Call `:to_secondary_section()` on the 1st client.", function() --DOC_HIDE + client.get()[1]:to_secondary_section() +end) --DOC_HIDE + +module.display_tags() --DOC_HIDE + +module.execute { display_screen = true , display_clients = true, --DOC_HIDE + display_label = false, display_client_name = true, --DOC_HIDE + display_mouse = true , --DOC_HIDE +} --DOC_HIDE From 56256d0c38a449125e8e81439c8495cb6e0c260c Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sat, 16 Oct 2021 17:07:18 -0700 Subject: [PATCH 09/18] shims: Add client.first_tag. --- tests/examples/shims/client.lua | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/tests/examples/shims/client.lua b/tests/examples/shims/client.lua index 208fe7c26..33a22b77e 100644 --- a/tests/examples/shims/client.lua +++ b/tests/examples/shims/client.lua @@ -62,6 +62,10 @@ function properties.set_screen(self, s) self:emit_signal("property::screen") end +function properties:get_first_tag() + return self:tags()[1] +end + -- Create fake clients to move around function client.gen_fake(args) local ret = gears_obj() @@ -126,7 +130,15 @@ function client.gen_fake(args) end function ret:isvisible() - return true + if ret.minimized or ret.hidden then return false end + + local vis = false + + for _, tag in ipairs(ret:tags()) do + vis = vis or tag.selected + end + + return vis end -- Used for screenshots From fd8401a39953c10cd342cd37a667cd76063d1a32 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sat, 16 Oct 2021 18:29:38 -0700 Subject: [PATCH 10/18] shims: Send the property:: signal for the client class. --- tests/examples/shims/client.lua | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/tests/examples/shims/client.lua b/tests/examples/shims/client.lua index 33a22b77e..d3f69d7b0 100644 --- a/tests/examples/shims/client.lua +++ b/tests/examples/shims/client.lua @@ -288,10 +288,14 @@ function client.gen_fake(args) ret.drawable = ret -- Make sure the layer properties are not `nil` - ret.ontop = false - ret.below = false - ret.above = false - ret.sticky = false + local defaults = { + ontop = false, + below = false, + above = false, + sticky = false, + urgent = false, + focusable = true, + } -- Declare the deprecated buttons and keys methods. function ret:_keys(new) @@ -319,6 +323,8 @@ function client.gen_fake(args) __index = function(self, key) if properties["get_"..key] then return properties["get_"..key](self) + elseif defaults[key] ~= nil then + return defaults[key] end return meta.__index(self, key) @@ -329,7 +335,14 @@ function client.gen_fake(args) return properties["set_"..key](self, value) end - return meta.__newindex(self, key, value) + if defaults[key] ~= nil then + defaults[key] = value + else + meta.__newindex(self, key, value) + end + + ret:emit_signal("property::"..key, value) + --client.emit_signal("property::"..key, ret, value) end }) From 73625168f23237ff07ea48991d6f08cc22ad0f64 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sat, 16 Oct 2021 18:56:31 -0700 Subject: [PATCH 11/18] doc: Improve the `awful` template. * Support client shape * Support titlebar colors * Only render clients part of the selected tag(s). --- tests/examples/awful/template.lua | 30 ++++++++++++++++++++++++++---- 1 file changed, 26 insertions(+), 4 deletions(-) diff --git a/tests/examples/awful/template.lua b/tests/examples/awful/template.lua index 4db97c3ac..5e01691f0 100644 --- a/tests/examples/awful/template.lua +++ b/tests/examples/awful/template.lua @@ -98,10 +98,20 @@ local total_area = wibox.layout { } local function wrap_titlebar(tb, width, height) + + local bg, fg + + if args.honor_titlebar_colors then + bg = tb.drawable.background_color or tb.args.bg_normal + fg = tb.drawable.foreground_color or tb.args.fg_normal + else + bg, fg = tb.args.bg_normal, tb.args.fg_normal + end + return wibox.widget { tb.drawable.widget, - bg = tb.args.bg_normal, - fg = tb.args.fg_normal, + bg = bg, + fg = fg, forced_width = width, forced_height = height, widget = wibox.container.background @@ -160,10 +170,15 @@ local function client_widget(c, col, label) border_color = bc, shape_clip = true, border_strategy = "inner", + opacity = c.opacity, fg = beautiful.fg_normal or "#000000", bg = col, shape = function(cr2, w, h) - return shape.rounded_rect(cr2, w, h, args.radius or 5) + if c.shape then + c.shape(cr2, w, h) + else + return shape.rounded_rect(cr2, w, h, args.radius or 5) + end end, forced_width = geo.width + 2*bw, @@ -201,7 +216,14 @@ end -- Loop each clients geometry history and paint it for _, c in ipairs(client.get()) do - if not c.minimized then + + local is_displayed = false + + for _, t in pairs(c:tags()) do + is_displayed = is_displayed or t.selected + end + + if (not c.minimized) and is_displayed then local pgeo = nil for _, geo in ipairs(c._old_geo) do if not geo._hide then From c7df6757ec8fbfccfca8fa2e7dbb7dbe05495e5f Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sat, 16 Oct 2021 18:57:56 -0700 Subject: [PATCH 12/18] titlebar: Add `urgent` colors. Just the bg/fg/bgimage, not all buttons. the reason is for consistency with the tasklist or border_color. --- lib/awful/titlebar.lua | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/lib/awful/titlebar.lua b/lib/awful/titlebar.lua index ae91c664c..fe16719a7 100644 --- a/lib/awful/titlebar.lua +++ b/lib/awful/titlebar.lua @@ -92,6 +92,21 @@ local titlebar = { -- @tparam gears.surface|string path -- @see gears.surface +--- The urgent titlebar foreground (text) color. +-- @beautiful beautiful.titlebar_fg_urgent +-- @param color +-- @see gears.color + +--- The urgent titlebar background color. +-- @beautiful beautiful.titlebar_bg_urgent +-- @param color +-- @see gears.color + +--- The urgent titlebar background image image. +-- @beautiful beautiful.titlebar_bgimage_urgent +-- @tparam gears.surface|string path +-- @see gears.surface + --- floating_button_normal. -- @beautiful beautiful.titlebar_floating_button_normal -- @tparam gears.surface|string path @@ -443,7 +458,10 @@ local all_titlebars = setmetatable({}, { __mode = 'k' }) -- Get a color for a titlebar, this tests many values from the array and the theme local function get_color(name, c, args) local suffix = "_normal" - if c.active then + + if c.urgent then + suffix = "_urgent" + elseif c.active then suffix = "_focus" end local function get(array) @@ -525,10 +543,12 @@ end -- `"left"`, `"right"` and `"bottom"`. -- @tparam[opt] string args.bg_normal -- @tparam[opt] string args.bg_focus +-- @tparam[opt] string args.bg_urgent -- @tparam[opt] string args.bgimage_normal -- @tparam[opt] string args.bgimage_focus -- @tparam[opt] string args.fg_normal -- @tparam[opt] string args.fg_focus +-- @tparam[opt] string args.fg_urgent -- @tparam[opt] string args.font -- @constructorfct awful.titlebar -- @treturn wibox.drawable The newly created titlebar object. @@ -568,6 +588,7 @@ local function new(c, args) -- Update the colors when focus changes c:connect_signal("property::active", update_colors) + c:connect_signal("property::urgent", update_colors) -- Inform the drawable when it becomes invisible c:connect_signal("request::unmanage", function() From 93283a98851aa0cc60918bb8d468b712eba9ad8c Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sat, 16 Oct 2021 20:55:21 -0700 Subject: [PATCH 13/18] doc: Undocument internal client `urgent` and `shape` methods. There is already some permissions to change the behavior. I don't think there is valid user-facing use cases for these "methods". --- docs/config.ld | 2 ++ lib/awful/client/urgent.lua | 6 +++--- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/config.ld b/docs/config.ld index feaa3eae2..99ea11879 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -517,6 +517,7 @@ file = { -- exclude these modules, as they do not contain any written -- documentation '../lib/awful/autofocus.lua', + '../lib/awful/client/shape.lua', '../lib/awful/dbus.lua', '../lib/awful/_compat.lua', '../lib/awful/init.lua', @@ -525,6 +526,7 @@ file = { '../lib/awful/startup_notification.lua', '../lib/awful/mouse/drag_to_tag.lua', '../lib/awful/permissions/_common.lua', + '../lib/awful/client/urgent.lua', '../lib/gears/init.lua', '../lib/wibox/layout/init.lua', '../lib/wibox/container/init.lua', diff --git a/lib/awful/client/urgent.lua b/lib/awful/client/urgent.lua index 49cf36470..82535f623 100644 --- a/lib/awful/client/urgent.lua +++ b/lib/awful/client/urgent.lua @@ -26,7 +26,7 @@ end local data = setmetatable({}, { __mode = 'k' }) ---- Get the first client that got the urgent hint. +-- Get the first client that got the urgent hint. -- -- @function awful.urgent.get -- @treturn client.object The first urgent client. @@ -57,7 +57,7 @@ function urgent.jumpto(merge) end end ---- Adds client to urgent stack. +-- Adds client to urgent stack. -- -- @function awful.urgent.add -- @tparam client c The client object. @@ -88,7 +88,7 @@ function urgent.add(c, prop) end end ---- Remove client from urgent stack. +-- Remove client from urgent stack. -- -- @function awful.urgent.delete -- @tparam client c The client object. From a8d2fa0297bd88770e6ecdf88d537a3fdb781532 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sat, 16 Oct 2021 21:58:25 -0700 Subject: [PATCH 14/18] doc: Add a large number of `client` examples. Backfill some under-documented APIs with yet more shiny images. --- lib/awful/client.lua | 67 +++++++++- lib/awful/client/urgent.lua | 8 +- lib/awful/permissions/init.lua | 7 +- objects/client.c | 69 +++++++++- tests/examples/awful/client/opacity1.lua | 96 ++++++++++++++ tests/examples/awful/client/shape1.lua | 100 ++++++++++++++ .../examples/awful/client/skip_tasklist1.lua | 97 ++++++++++++++ tests/examples/awful/client/urgent1.lua | 125 ++++++++++++++++++ tests/examples/sequences/client/activate1.lua | 64 +++++++++ .../sequences/client/activate1.output.txt | 1 + tests/examples/sequences/client/floating1.lua | 34 +++++ tests/examples/sequences/client/geometry1.lua | 52 ++++++++ .../sequences/client/geometry1.output.txt | 1 + tests/examples/sequences/client/height1.lua | 29 ++++ tests/examples/sequences/client/jump_to1.lua | 45 +++++++ tests/examples/sequences/client/kill1.lua | 50 +++++++ tests/examples/sequences/client/minimize1.lua | 43 ++++++ .../sequences/client/move_to_screen1.lua | 54 ++++++++ .../sequences/client/move_to_tag1.lua | 33 +++++ .../sequences/client/relative_move1.lua | 61 +++++++++ .../client/relative_move1.output.txt | 2 + tests/examples/sequences/client/tags1.lua | 42 ++++++ .../sequences/client/tags1.output.txt | 2 + .../sequences/client/to_selected_tags1.lua | 40 ++++++ .../examples/sequences/client/toggle_tag1.lua | 33 +++++ tests/examples/sequences/client/width1.lua | 29 ++++ tests/examples/sequences/client/x1.lua | 29 ++++ tests/examples/sequences/client/y1.lua | 29 ++++ tests/examples/sequences/template.lua | 15 ++- 29 files changed, 1239 insertions(+), 18 deletions(-) create mode 100644 tests/examples/awful/client/opacity1.lua create mode 100644 tests/examples/awful/client/shape1.lua create mode 100644 tests/examples/awful/client/skip_tasklist1.lua create mode 100644 tests/examples/awful/client/urgent1.lua create mode 100644 tests/examples/sequences/client/activate1.lua create mode 100644 tests/examples/sequences/client/activate1.output.txt create mode 100644 tests/examples/sequences/client/floating1.lua create mode 100644 tests/examples/sequences/client/geometry1.lua create mode 100644 tests/examples/sequences/client/geometry1.output.txt create mode 100644 tests/examples/sequences/client/height1.lua create mode 100644 tests/examples/sequences/client/jump_to1.lua create mode 100644 tests/examples/sequences/client/kill1.lua create mode 100644 tests/examples/sequences/client/minimize1.lua create mode 100644 tests/examples/sequences/client/move_to_screen1.lua create mode 100644 tests/examples/sequences/client/move_to_tag1.lua create mode 100644 tests/examples/sequences/client/relative_move1.lua create mode 100644 tests/examples/sequences/client/relative_move1.output.txt create mode 100644 tests/examples/sequences/client/tags1.lua create mode 100644 tests/examples/sequences/client/tags1.output.txt create mode 100644 tests/examples/sequences/client/to_selected_tags1.lua create mode 100644 tests/examples/sequences/client/toggle_tag1.lua create mode 100644 tests/examples/sequences/client/width1.lua create mode 100644 tests/examples/sequences/client/x1.lua create mode 100644 tests/examples/sequences/client/y1.lua diff --git a/lib/awful/client.lua b/lib/awful/client.lua index 44b2107a5..6b66d8ed7 100644 --- a/lib/awful/client.lua +++ b/lib/awful/client.lua @@ -168,8 +168,11 @@ function client.jumpto(c, merge) end --- Jump to the given client. +-- -- Takes care of focussing the screen, the right tag, etc. -- +-- @DOC_sequences_client_jump_to1_EXAMPLE@ +-- -- @method jump_to -- @tparam bool|function merge If true then merge tags (select the client's -- first tag additionally) when the client is not visible. @@ -502,6 +505,9 @@ function client.moveresize(x, y, w, h, c) end --- Move/resize a client relative to current coordinates. +-- +-- @DOC_sequences_client_relative_move1_EXAMPLE@ +-- -- @method relative_move -- @see geometry -- @tparam[opt=c.x] number x The relative x coordinate. @@ -510,10 +516,10 @@ end -- @tparam[opt=c.height] number h The relative height. function client.object.relative_move(self, x, y, w, h) local geometry = self:geometry() - geometry['x'] = geometry['x'] + x - geometry['y'] = geometry['y'] + y - geometry['width'] = geometry['width'] + w - geometry['height'] = geometry['height'] + h + geometry['x'] = geometry['x'] + (x or geometry.x) + geometry['y'] = geometry['y'] + (y or geometry.y) + geometry['width'] = geometry['width'] + (w or geometry.width) + geometry['height'] = geometry['height'] + (h or geometry.height) self:geometry(geometry) end @@ -529,6 +535,8 @@ end --- Move a client to a tag. -- +-- @DOC_sequences_client_move_to_tag1_EXAMPLE@ +-- -- @method move_to_tag -- @tparam tag target The tag to move the client to. -- @request client activate client.movetotag granted When a client could be @@ -560,6 +568,8 @@ end --- Toggle a tag on a client. -- +-- @DOC_sequences_client_toggle_tag1_EXAMPLE@ +-- -- @method toggle_tag -- @tparam tag target The tag to move the client to. -- @see tags @@ -597,6 +607,9 @@ function client.movetoscreen(c, s) end --- Move a client to a screen. Default is next screen, cycling. +-- +-- @DOC_sequences_client_move_to_screen1_EXAMPLE@ +-- -- @method move_to_screen -- @tparam[opt=c.screen.index+1] screen s The screen, default to current + 1. -- @see screen @@ -647,6 +660,8 @@ end -- tags at the point of calling this method, it will fall back to the screen's -- full set of tags. -- +-- @DOC_sequences_client_to_selected_tags1_EXAMPLE@ +-- -- @method to_selected_tags -- @see screen.selected_tags function client.object.to_selected_tags(self) @@ -895,6 +910,8 @@ end -- did not set them manually. For example, windows with a type different than -- normal. -- +-- @DOC_sequences_client_floating1_EXAMPLE@ +-- -- @property floating -- @tparam boolean floating The floating state. -- @request client border floating granted When a border update is required @@ -976,6 +993,12 @@ end --- The x coordinates. -- +-- `x` (usually) originate from the top left. `x` does *not* include +-- the outer client border, but rather where the content and/or titlebar +-- starts. +-- +-- @DOC_sequences_client_x1_EXAMPLE@ +-- -- @property x -- @tparam integer x -- @emits property::geometry @@ -983,9 +1006,17 @@ end -- geometry (with `x`, `y`, `width`, `height`). -- @emits property::x -- @emits property::position +-- @see geometry +-- @see relative_move --- The y coordinates. -- +-- `y` (usually) originate from the top left. `y` does *not* include +-- the outer client border, but rather where the content and/or titlebar +-- starts. +-- +-- @DOC_sequences_client_y1_EXAMPLE@ +-- -- @property y -- @tparam integer y -- @emits property::geometry @@ -993,9 +1024,13 @@ end -- geometry (with `x`, `y`, `width`, `height`). -- @emits property::y -- @emits property::position +-- @see geometry +-- @see relative_move --- The width of the client. -- +-- @DOC_sequences_client_width1_EXAMPLE@ +-- -- @property width -- @tparam integer width -- @emits property::geometry @@ -1003,9 +1038,13 @@ end -- geometry (with `x`, `y`, `width`, `height`). -- @emits property::width -- @emits property::size +-- @see geometry +-- @see relative_move --- The height of the client. -- +-- @DOC_sequences_client_height1_EXAMPLE@ +-- -- @property height -- @tparam integer height -- @emits property::geometry @@ -1013,6 +1052,8 @@ end -- geometry (with `x`, `y`, `width`, `height`). -- @emits property::height -- @emits property::size +-- @see geometry +-- @see relative_move -- Add the geometry helpers to match the wibox API for _, v in ipairs {"x", "y", "width", "height"} do @@ -1239,6 +1280,7 @@ end -- @property dockable -- @tparam boolean dockable The dockable state -- @propemits false false +-- @see struts function client.object.get_dockable(c) local value = client.property.get(c, "dockable") @@ -1271,7 +1313,7 @@ end --- If the client requests not to be decorated with a titlebar. -- -- The motif wm hints allow a client to request not to be decorated by the WM in --- various ways. This property uses the motif MWM_DECOR_TITLE hint and +-- various ways. This property uses the motif `MWM_DECOR_TITLE` hint and -- interprets it as the client (not) wanting a titlebar. -- -- @property requests_no_titlebar @@ -1513,6 +1555,8 @@ end, true, true, "keybinding") --- Set the client shape. -- +-- @DOC_awful_client_shape1_EXAMPLE@ +-- -- @property shape -- @tparam gears.shape A gears.shape compatible function. -- @propemits true false @@ -1556,10 +1600,13 @@ end -- isn't already within its geometry, -- * **toggle_minimization**: If the client is already active, minimize it. -- +-- @DOC_sequences_client_activate1_EXAMPLE@ +-- -- @method activate -- @tparam table args -- @tparam[opt=other] string args.context Why was this activate called? --- @tparam[opt=true] boolean args.raise Raise the client to the top of its layer. +-- @tparam[opt=true] boolean args.raise Raise the client to the top of its layer +-- and unminimize it (if needed). -- @tparam[opt=false] boolean args.force Force the activation even for unfocusable -- clients. -- @tparam[opt=false] boolean args.switch_to_tags @@ -1567,6 +1614,7 @@ end -- @tparam[opt=false] boolean args.action Once activated, perform an action. -- @tparam[opt=false] boolean args.toggle_minimization -- @see awful.permissions.add_activate_filter +-- @see awful.permissions.activate -- @see request::activate -- @see active function client.object.activate(c, args) @@ -1735,6 +1783,13 @@ end) -- @classsignal -- @see awful.permissions.update_border +--- Jump to the client that received the urgent hint first. +-- +-- @staticfct awful.client.urgent.jumpto +-- @tparam bool|function merge If true then merge tags (select the client's +-- first tag additionally) when the client is not visible. +-- If it is a function, it will be called with the client as argument. + -- Add clients during startup to focus history. -- This used to happen through permissions.activate, but that only handles visible -- clients now. diff --git a/lib/awful/client/urgent.lua b/lib/awful/client/urgent.lua index 82535f623..16c429dd9 100644 --- a/lib/awful/client/urgent.lua +++ b/lib/awful/client/urgent.lua @@ -28,7 +28,7 @@ local data = setmetatable({}, { __mode = 'k' }) -- Get the first client that got the urgent hint. -- --- @function awful.urgent.get +-- @function awful.client.urgent.get -- @treturn client.object The first urgent client. function urgent.get() if #data > 0 then @@ -46,7 +46,7 @@ end --- Jump to the client that received the urgent hint first. -- --- @function awful.urgent.jumpto +-- @function awful.client.urgent.jumpto -- @tparam bool|function merge If true then merge tags (select the client's -- first tag additionally) when the client is not visible. -- If it is a function, it will be called with the client as argument. @@ -59,7 +59,7 @@ end -- Adds client to urgent stack. -- --- @function awful.urgent.add +-- @function awful.client.urgent.add -- @tparam client c The client object. -- @param prop The property which is updated. -- @request client border active granted When a client becomes active and is no @@ -90,7 +90,7 @@ end -- Remove client from urgent stack. -- --- @function awful.urgent.delete +-- @function awful.client.urgent.delete -- @tparam client c The client object. function urgent.delete(c) for k, cl in ipairs(data) do diff --git a/lib/awful/permissions/init.lua b/lib/awful/permissions/init.lua index d63f603d9..909544293 100644 --- a/lib/awful/permissions/init.lua +++ b/lib/awful/permissions/init.lua @@ -133,7 +133,9 @@ end --- Activate a window. -- --- This sets the focus only if the client is visible. +-- This sets the focus only if the client is visible. If `raise` is set +-- in the hints, it will also unminimize the client and move it to the top +-- of its layer. -- -- It is the default signal handler for `request::activate` on a `client`. -- @@ -141,7 +143,8 @@ end -- @tparam client c A client to use -- @tparam string context The context where this signal was used. -- @tparam[opt] table hints A table with additional hints: --- @tparam[opt=false] boolean hints.raise should the client be raised? +-- @tparam[opt=false] boolean hints.raise should the client be unminimized +-- and raised? -- @tparam[opt=false] boolean hints.switch_to_tag should the client's first tag -- be selected if none of the client's tags are selected? -- @tparam[opt=false] boolean hints.switch_to_tags Select all tags associated diff --git a/objects/client.c b/objects/client.c index 19ad5f3f5..f8b78e5f5 100644 --- a/objects/client.c +++ b/objects/client.c @@ -475,10 +475,14 @@ lua_class_t client_class; * `_NET_WM_STATE_SKIP_TASKBAR` X11 protocol xproperty. Clients can modify this * state through this property. * + * @DOC_awful_client_skip_tasklist1_EXAMPLE@ + * * @property skip_taskbar * @tparam[opt=false] boolean skip_taskbar * @propemits false false * @see sticky + * @see hidden + * @see unmanage */ /** @@ -697,16 +701,28 @@ lua_class_t client_class; * @tparam boolean hidden * @propemits false false * @see minimized + * @see skip_taskbar + * @see unmanage */ /** * Define it the client must be iconify, i.e. only visible in * taskbar. * + * Minimized clients are still part of tags and screens, but + * they are not displayed. You can unminimize using `c.minimized = false`, + * but if you also want to set the focus, it is better to use: + * + * c:activate { context = "unminimized", raise = true } + * + * @DOC_sequences_client_minimize1_EXAMPLE@ + * * @property minimized * @tparam boolean minimized * @propemits false false * @see hidden + * @see isvisible + * @see activate */ /** @@ -819,12 +835,34 @@ lua_class_t client_class; */ /** - * The client urgent state. + * Set to `true` when the client ask for attention. + * + * The urgent state is the visual equivalent of the "bell" noise from + * old computer. It is set by the client when their state changed and + * they need attention. For example, a chat client will set it when + * a new message arrive. Some terminals, like `rxvt-unicode`, will also + * set it when calling the `bell` command. + * + * There is many ways an urgent client can become for visible: + * + * * Highlight in the `awful.widget.taglist` and `awful.widget.tasklist` + * * Highlight in the `awful.titlebar` + * * Highlight of the client border color (or width). + * * Accessible using `Mod4+u` in the default config. + * * Emit the `property::urgent` signal. + * + * @DOC_awful_client_urgent1_EXAMPLE@ * * @property urgent * @tparam boolean urgent * @propemits false false + * @request client border active granted When a client becomes active and is no + * longer urgent. + * @request client border inactive granted When a client stop being active and + * is no longer urgent. + * @request client border urgent granted When a client stop becomes urgent. * @see request::border + * @see awful.client.urgent.jumpto * @usebeautiful beautiful.border_color_urgent The fallback color when the * client is urgent. * @usebeautiful beautiful.border_color_floating_urgent The color when the @@ -841,6 +879,11 @@ lua_class_t client_class; * the client is maximized and urgent. * @usebeautiful beautiful.border_width_fullscreen_urgent The border width when * the client is fullscreen and urgent. + * @usebeautiful beautiful.titlebar_fg_urgent + * @usebeautiful beautiful.titlebar_bg_urgent + * @usebeautiful beautiful.titlebar_bgimage_urgent + * @usebeautiful beautiful.fg_urgent + * @usebeautiful beautiful.bg_urgent */ /** @@ -875,10 +918,17 @@ lua_class_t client_class; /** * The client opacity. * + * The opacity only works when a compositing manager, such as + * [picom](https://github.com/yshui/picom/), is used. Otherwise, + * the clients will remain opaque. + * + * @DOC_awful_client_opacity1_EXAMPLE@ + * * @property opacity * @tparam number opacity Between 0 (transparent) to 1 (opaque). * @propemits false false * @see request::border + * @see awesome.composite_manager_running */ /** @@ -1365,6 +1415,7 @@ lua_class_t client_class; * @method struts * @see geometry * @see screen.workarea + * @see dockable */ /** Get or set mouse buttons bindings for a client. @@ -1373,6 +1424,9 @@ lua_class_t client_class; * @tparam table buttons * @propemits false false * @see awful.button + * @see append_mousebinding + * @see remove_mousebinding + * @see request::default_mousebindings */ /** Get the number of instances. @@ -2922,7 +2976,7 @@ client_kill(client_t *c) /** Get all clients into a table. * - * @tparam[opt] integer screen A screen number to filter clients on. + * @tparam[opt] integer|screen screen A screen number to filter clients on. * @tparam[opt] boolean stacked Return clients in stacking order? (ordered from * top to bottom). * @treturn table A table with clients. @@ -3082,7 +3136,9 @@ out: * * This method can be used to close (kill) a **client** using the * X11 protocol. To use the POSIX way to kill a **process**, use - * `awesome.kill`. + * `awesome.kill` (using the client `pid` property). + * + * @DOC_sequences_client_kill1_EXAMPLE@ * * @method kill * @see awesome.kill @@ -3154,6 +3210,8 @@ luaA_client_swap(lua_State *L) * * Use the `first_tag` field to access the first tag of a client directly. * + * @DOC_sequences_client_tags1_EXAMPLE@ + * * @tparam table tags_table A table with tags to set, or `nil` to get the * current tags. * @treturn table A table with all tags. @@ -3514,6 +3572,8 @@ HANDLE_TITLEBAR(bottom, CLIENT_TITLEBAR_BOTTOM) HANDLE_TITLEBAR(left, CLIENT_TITLEBAR_LEFT) /** Return or set client geometry. + * + * @DOC_sequences_client_geometry1_EXAMPLE@ * * @tparam table|nil geo A table with new coordinates, or nil. * @tparam integer geo.x The horizontal position. @@ -4190,6 +4250,9 @@ luaA_client_set_shape_input(lua_State *L, client_t *c) * @tparam table keys * @propemits false false * @see awful.key + * @see append_keybinding + * @see remove_keybinding + * @see request::default_keybindings */ static int luaA_client_keys(lua_State *L) diff --git a/tests/examples/awful/client/opacity1.lua b/tests/examples/awful/client/opacity1.lua new file mode 100644 index 000000000..3ecdcb72d --- /dev/null +++ b/tests/examples/awful/client/opacity1.lua @@ -0,0 +1,96 @@ +--DOC_NO_USAGE --DOC_GEN_IMAGE --DOC_ASTERISK --DOC_HIDE_START +local awful = require("awful") +local wibox = require("wibox") +local beautiful = require("beautiful") + +screen[1]._resize {width = 480, height = 200} + +local wb = awful.wibar { position = "top" } + +-- Create the same number of tags as the default config +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.layouts[1]) + +-- Only bother with widgets that are visible by default +local mykeyboardlayout = awful.widget.keyboardlayout() +local mytextclock = wibox.widget.textclock() +local mytaglist = awful.widget.taglist(screen[1], awful.widget.taglist.filter.all, {}) +local mytasklist = awful.widget.tasklist(screen[1], awful.widget.tasklist.filter.currenttags, {}) + +client.connect_signal("request::titlebars", function(c) + local top_titlebar = awful.titlebar(c, { + height = 20, + bg_normal = beautiful.bg_normal, + }) + + top_titlebar : setup { + { -- Left + awful.titlebar.widget.iconwidget(c), + layout = wibox.layout.fixed.horizontal + }, + { -- Middle + { -- Title + align = "center", + widget = awful.titlebar.widget.titlewidget(c) + }, + layout = wibox.layout.flex.horizontal + }, + { -- Right + awful.titlebar.widget.floatingbutton (c), + awful.titlebar.widget.maximizedbutton(c), + awful.titlebar.widget.stickybutton (c), + awful.titlebar.widget.ontopbutton (c), + awful.titlebar.widget.closebutton (c), + layout = wibox.layout.fixed.horizontal() + }, + layout = wibox.layout.align.horizontal + } +end) + + +wb:setup { + layout = wibox.layout.align.horizontal, + { + mytaglist, + layout = wibox.layout.fixed.horizontal, + }, + mytasklist, + { + layout = wibox.layout.fixed.horizontal, + mykeyboardlayout, + mytextclock, + }, +} + +require("gears.timer").run_delayed_calls_now() +local counter = 0 + +local function gen_client(label) + local c = client.gen_fake {hide_first=true} + + c:geometry { + x = 45 + counter*1.75, + y = 30 + counter, + height = 60, + width = 230, + } + c._old_geo = {c:geometry()} + c:set_label(label) + c:emit_signal("request::titlebars") + c.border_color = beautiful.bg_highlight + c.border_width = 2 + counter = counter + 40 + + return c +end + + local c1 = gen_client("Opacity: 1") + local c2 = gen_client("Opacity: 0.5") + local c3 = gen_client("Opacity: 0.1") +--DOC_HIDE_END + + c1.opacity = 1 + c2.opacity = 0.5 + c3.opacity = 0.1 + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 + diff --git a/tests/examples/awful/client/shape1.lua b/tests/examples/awful/client/shape1.lua new file mode 100644 index 000000000..c8bf2e37d --- /dev/null +++ b/tests/examples/awful/client/shape1.lua @@ -0,0 +1,100 @@ +--DOC_NO_USAGE --DOC_GEN_IMAGE --DOC_HIDE_START +local awful = require("awful") +local wibox = require("wibox") +local beautiful = require("beautiful") +local gears = { shape = require("gears.shape") } + +screen[1]._resize {width = 480, height = 200} + +awful.client.object.set_shape = nil +awful.client.object.get_shape = nil + +local wb = awful.wibar { position = "top" } + +-- Create the same number of tags as the default config +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.layouts[1]) + +-- Only bother with widgets that are visible by default +local mykeyboardlayout = awful.widget.keyboardlayout() +local mytextclock = wibox.widget.textclock() +local mytaglist = awful.widget.taglist(screen[1], awful.widget.taglist.filter.all, {}) +local mytasklist = awful.widget.tasklist(screen[1], awful.widget.tasklist.filter.currenttags, {}) + +client.connect_signal("request::titlebars", function(c) + local top_titlebar = awful.titlebar(c, { + height = 20, + bg_normal = beautiful.bg_normal, + }) + + top_titlebar : setup { + { -- Left + awful.titlebar.widget.iconwidget(c), + layout = wibox.layout.fixed.horizontal + }, + { -- Middle + { -- Title + align = "center", + widget = awful.titlebar.widget.titlewidget(c) + }, + layout = wibox.layout.flex.horizontal + }, + { -- Right + awful.titlebar.widget.floatingbutton (c), + awful.titlebar.widget.maximizedbutton(c), + awful.titlebar.widget.stickybutton (c), + awful.titlebar.widget.ontopbutton (c), + awful.titlebar.widget.closebutton (c), + layout = wibox.layout.fixed.horizontal() + }, + layout = wibox.layout.align.horizontal + } +end) + + +wb:setup { + layout = wibox.layout.align.horizontal, + { + mytaglist, + layout = wibox.layout.fixed.horizontal, + }, + mytasklist, + { + layout = wibox.layout.fixed.horizontal, + mykeyboardlayout, + mytextclock, + }, +} + +require("gears.timer").run_delayed_calls_now() +local counter = 0 + +local function gen_client(label) + local c = client.gen_fake {hide_first=true} + + c:geometry { + x = 45 + counter*1.75, + y = 30 + counter, + height = 60, + width = 230, + } + c._old_geo = {c:geometry()} + c.border_width = 2 + c:set_label(label) + c:emit_signal("request::titlebars") + c.border_color = beautiful.bg_highlight + counter = counter + 40 + + return c +end + + local c1 = gen_client("Rectangle (default)") + local c2 = gen_client("Rounded rect") + local c3 = gen_client("Octogon") + +--DOC_HIDE_END + c1.shape = gears.shape.rectangle + c2.shape = gears.shape.rounded_rect + c3.shape = gears.shape.octogon + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 + diff --git a/tests/examples/awful/client/skip_tasklist1.lua b/tests/examples/awful/client/skip_tasklist1.lua new file mode 100644 index 000000000..1b0911bd5 --- /dev/null +++ b/tests/examples/awful/client/skip_tasklist1.lua @@ -0,0 +1,97 @@ +--DOC_NO_USAGE --DOC_GEN_IMAGE --DOC_ASTERISK --DOC_HIDE_START +local awful = require("awful") +local wibox = require("wibox") +local beautiful = require("beautiful") + +screen[1]._resize {width = 480, height = 200} + +local wb = awful.wibar { position = "top" } + +-- Create the same number of tags as the default config +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.layouts[1]) + +-- Only bother with widgets that are visible by default +local mykeyboardlayout = awful.widget.keyboardlayout() +local mytextclock = wibox.widget.textclock() +local mytaglist = awful.widget.taglist(screen[1], awful.widget.taglist.filter.all, {}) +local mytasklist = awful.widget.tasklist(screen[1], awful.widget.tasklist.filter.currenttags, {}) + +client.connect_signal("request::titlebars", function(c) + local top_titlebar = awful.titlebar(c, { + height = 20, + bg_normal = beautiful.bg_normal, + }) + + top_titlebar : setup { + { -- Left + awful.titlebar.widget.iconwidget(c), + layout = wibox.layout.fixed.horizontal + }, + { -- Middle + { -- Title + align = "center", + widget = awful.titlebar.widget.titlewidget(c) + }, + layout = wibox.layout.flex.horizontal + }, + { -- Right + awful.titlebar.widget.floatingbutton (c), + awful.titlebar.widget.maximizedbutton(c), + awful.titlebar.widget.stickybutton (c), + awful.titlebar.widget.ontopbutton (c), + awful.titlebar.widget.closebutton (c), + layout = wibox.layout.fixed.horizontal() + }, + layout = wibox.layout.align.horizontal + } +end) + + +wb:setup { + layout = wibox.layout.align.horizontal, + { + mytaglist, + layout = wibox.layout.fixed.horizontal, + }, + mytasklist, + { + layout = wibox.layout.fixed.horizontal, + mykeyboardlayout, + mytextclock, + }, +} + +require("gears.timer").run_delayed_calls_now() +local counter = 0 + +local function gen_client(label) + local c = client.gen_fake {hide_first=true} + + c:geometry { + x = 45 + counter*1.75, + y = 30 + counter, + height = 60, + width = 230, + } + c._old_geo = {c:geometry()} + c:set_label(label) + c:emit_signal("request::titlebars") + c.border_color = beautiful.bg_highlight + c.name = label + counter = counter + 40 + + return c +end + + local c1 = gen_client("Client 1 (in tasktar)") + local c2 = gen_client("Client 2 (NOT in taskbar)") + local c3 = gen_client("Client 3 (in taskbar)") + +--DOC_HIDE_END + + c1.skip_taskbar = false + c2.skip_taskbar = true + c3.skip_taskbar = false + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 + diff --git a/tests/examples/awful/client/urgent1.lua b/tests/examples/awful/client/urgent1.lua new file mode 100644 index 000000000..6527fb1ba --- /dev/null +++ b/tests/examples/awful/client/urgent1.lua @@ -0,0 +1,125 @@ +--DOC_NO_USAGE --DOC_GEN_IMAGE --DOC_ASTERISK --DOC_HIDE_START +local awful = require("awful") +local wibox = require("wibox") +local beautiful = require("beautiful") + +screen[1]._resize {width = 480, height = 200} + +local wb = awful.wibar { position = "top" } + +-- Create the same number of tags as the default config +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.layouts[1]) + +-- Only bother with widgets that are visible by default +local mykeyboardlayout = awful.widget.keyboardlayout() +local mytextclock = wibox.widget.textclock() +local mytaglist = awful.widget.taglist(screen[1], awful.widget.taglist.filter.all, {}) +local mytasklist = awful.widget.tasklist(screen[1], awful.widget.tasklist.filter.currenttags, {}) + +client.connect_signal("request::titlebars", function(c) + local top_titlebar = awful.titlebar(c, { + height = 20, + bg_normal = beautiful.bg_normal, + }) + + top_titlebar : setup { + { -- Left + awful.titlebar.widget.iconwidget(c), + layout = wibox.layout.fixed.horizontal + }, + { -- Middle + { -- Title + align = "center", + widget = awful.titlebar.widget.titlewidget(c) + }, + layout = wibox.layout.flex.horizontal + }, + { -- Right + awful.titlebar.widget.floatingbutton (c), + awful.titlebar.widget.maximizedbutton(c), + awful.titlebar.widget.stickybutton (c), + awful.titlebar.widget.ontopbutton (c), + awful.titlebar.widget.closebutton (c), + layout = wibox.layout.fixed.horizontal() + }, + layout = wibox.layout.align.horizontal + } +end) + + +wb:setup { + layout = wibox.layout.align.horizontal, + { + mytaglist, + layout = wibox.layout.fixed.horizontal, + }, + mytasklist, + { + layout = wibox.layout.fixed.horizontal, + mykeyboardlayout, + mytextclock, + }, +} + +require("gears.timer").run_delayed_calls_now() +local counter = 0 + +local function gen_client(label) + local c = client.gen_fake {hide_first=true} + + c:geometry { + x = 45 + counter*1.75, + y = 30 + counter, + height = 60, + width = 230, + } + c._old_geo = {c:geometry()} + c:set_label(label) + counter = counter + 40 + c.class = label + + return c +end + + local c1 = gen_client("Inactive") + local c2 = gen_client("Urgent") + local c3 = gen_client("Focus") + local c4 = gen_client("Tag") + + c4:tags{screen[1].tags[2]} +--DOC_HIDE_END + + -- Affects mostly the taglist and tasklist.. + beautiful.fg_urgent = "#ffffff" + beautiful.bg_urgent = "#ff0000" + + --DOC_NEWLINE + + -- Set the client border to be orange and large. + beautiful.border_color_urgent = "#ffaa00" + beautiful.border_width_urgent = 6 + + --DOC_NEWLINE + + -- Set the titlebar green. + beautiful.titlebar_bg_urgent = "#00ff00" + beautiful.titlebar_fg_urgent = "#000000" + + --DOC_NEWLINE + + -- This client is in the current tag. + c2.urgent = true + + --DOC_NEWLINE + + -- This client is in a deselected tag. + c4.urgent = true + +--DOC_HIDE_START + c1:emit_signal("request::titlebars") + c2:emit_signal("request::titlebars") + c3:emit_signal("request::titlebars") + +return {honor_titlebar_colors = true} +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 + diff --git a/tests/examples/sequences/client/activate1.lua b/tests/examples/sequences/client/activate1.lua new file mode 100644 index 000000000..0bc879d60 --- /dev/null +++ b/tests/examples/sequences/client/activate1.lua @@ -0,0 +1,64 @@ + --DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_GEN_OUTPUT --DOC_HIDE_START +local module = ... +local awful = {tag = require("awful.tag"), layout = require("awful.layout")} +local beautiful = require("beautiful") +require("awful.ewmh") +screen[1]._resize {x = 0, width = 160, height = 90} +awful.tag({ "one", "two", "three" }, screen[1], awful.layout.suit.tile) + +function awful.spawn(name, properties) + client.gen_fake{class = name, name = name, x = 10, y=10, width = 60, height =50, tags = properties.tags} +end + +local function color_focus() + for _, c in ipairs(client.get()) do + c.color = c.active and "#ff777733" or beautiful.bg_normal + end +end + +module.add_event("Spawn some apps", function() + for tag_idx = 1, 3 do + for i = 1, 3 do + awful.spawn("c"..((tag_idx-1)*3+i), {tags = {screen[1].tags[tag_idx]}}) + end + end + + client.get()[2]:activate{} + + color_focus() +end) + +--DOC_NEWLINE +module.display_tags() + +module.add_event('Activate "c8"', function() + -- Mitigate a bug in the shims. + client.get()[8]:activate { + switch_to_tag = true, + raise = true, + context = "somet_reason", + } + + --DOC_HIDE_END + + client.get()[8]:activate { + switch_to_tag = true, + raise = true, + context = "somet_reason", + } + + --DOC_NEWLINE + + -- Since this isnt denied by any permission, it will be true. + print( + "Confirm:", client.get()[8].active, client.focus == client.get()[8] + ) + + --DOC_HIDE_START + color_focus() +end) + +module.display_tags() + +module.execute { display_screen = false, display_clients = true , + display_label = false, display_client_name = true } diff --git a/tests/examples/sequences/client/activate1.output.txt b/tests/examples/sequences/client/activate1.output.txt new file mode 100644 index 000000000..aa52403d6 --- /dev/null +++ b/tests/examples/sequences/client/activate1.output.txt @@ -0,0 +1 @@ +Confirm: true true diff --git a/tests/examples/sequences/client/floating1.lua b/tests/examples/sequences/client/floating1.lua new file mode 100644 index 000000000..3766e668e --- /dev/null +++ b/tests/examples/sequences/client/floating1.lua @@ -0,0 +1,34 @@ + --DOC_GEN_IMAGE --DOC_NO_USAGE +local module = ... --DOC_HIDE +local awful = {tag = require("awful.tag"), layout = require("awful.layout")} --DOC_HIDE +require("awful.ewmh") --DOC_HIDE +screen[1]._resize {x = 0, width = 800, height = 600} --DOC_HIDE +awful.tag({ "one", "two", "three" }, screen[1], awful.layout.suit.tile) --DOC_HIDE + +function awful.spawn(name) --DOC_HIDE + client.gen_fake{class = name, name = name, x = 10, y=10, width = 60, height =50} --DOC_HIDE +end --DOC_HIDE + +module.add_event("Spawn some tiled apps", function() --DOC_HIDE + for i = 1, 5 do + awful.spawn("Client #"..i) + end + + client.get()[1].color = "#f8dcdb" --DOC_HIDE + +end) --DOC_HIDE + +--DOC_NEWLINE +module.display_tags() --DOC_HIDE + +module.add_event("Raise and un-tile", function() --DOC_HIDE + client.get()[1].floating = true + client.get()[1]:geometry {x= 100, y=150, width = 500, height = 300} --DOC_HIDE + client.get()[1]:raise() +end) --DOC_HIDE + + +module.display_tags() --DOC_HIDE + +module.execute { display_screen = true , display_clients = true , --DOC_HIDE + display_label = false, display_client_name = true } --DOC_HIDE diff --git a/tests/examples/sequences/client/geometry1.lua b/tests/examples/sequences/client/geometry1.lua new file mode 100644 index 000000000..fec629b8f --- /dev/null +++ b/tests/examples/sequences/client/geometry1.lua @@ -0,0 +1,52 @@ + --DOC_GEN_IMAGE --DOC_HIDE_START --DOC_ASTERISK --DOC_NO_USAGE --DOC_GEN_OUTPUT +local module = ... +require("ruled.client") +local awful = {tag = require("awful.tag"), layout = require("awful.layout")} +awful.placement = require("awful.placement") +require("awful.ewmh") +screen[1]:fake_resize(0, 0, 800, 480) +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.suit.tile) + +function awful.spawn(name) + client.gen_fake{class = name, name = name, x = 4, y=10, width = 60, height =50, screen=screen[1]} +end + +--DOC_NEWLINE + +module.add_event("Spawn a floating client.", function() + --DOC_HIDE_END + awful.spawn("") + + --DOC_NEWLINE + + client.get()[1].floating = true + + --DOC_NEWLINE + --DOC_HIDE_START +end) + +module.display_tags() + +module.add_event("Move and resize it.", function() + --DOC_HIDE_END + client.get()[1]:geometry { + x = 200, + y = 200, + width = 300, + height = 240 + } + --DOC_NEWLINE + + -- It can also read the geometry. + local geo = client.get()[1]:geometry() + print("Client geometry:", geo.x, geo.y, geo.width, geo.height) + + --DOC_HIDE_START +end) + +module.display_tags() + +module.execute { display_screen = true , display_clients = true, + display_label = false, display_client_name = true, + display_mouse = false, +} diff --git a/tests/examples/sequences/client/geometry1.output.txt b/tests/examples/sequences/client/geometry1.output.txt new file mode 100644 index 000000000..e952aa244 --- /dev/null +++ b/tests/examples/sequences/client/geometry1.output.txt @@ -0,0 +1 @@ +Client geometry: 200 200 300 240 diff --git a/tests/examples/sequences/client/height1.lua b/tests/examples/sequences/client/height1.lua new file mode 100644 index 000000000..ce04cf63a --- /dev/null +++ b/tests/examples/sequences/client/height1.lua @@ -0,0 +1,29 @@ + --DOC_GEN_IMAGE --DOC_NO_USAGE +local module = ... --DOC_HIDE +local awful = {tag = require("awful.tag"), layout = require("awful.layout")} --DOC_HIDE +require("awful.ewmh") --DOC_HIDE +screen[1]._resize {x = 0, width = 160, height = 90} --DOC_HIDE +awful.tag({ "one", "two", "three" }, screen[1], awful.layout.suit.tile) --DOC_HIDE + +function awful.spawn(name) --DOC_HIDE + client.gen_fake{class = name, name = name, x = 10, y=10, width = 60, height =50, floating = true} --DOC_HIDE +end --DOC_HIDE + +module.add_event("Spawn a client", function() --DOC_HIDE + awful.spawn("") --DOC_HIDE + + client.get()[1].color = "#ff777733" --DOC_HIDE + +end) --DOC_HIDE + +--DOC_NEWLINE +module.display_tags() --DOC_HIDE + +module.add_event("Change the `height` property", function() --DOC_HIDE + client.focus.height = 100 +end) --DOC_HIDE + +module.display_tags() --DOC_HIDE + +module.execute { display_screen = false, display_clients = true , --DOC_HIDE + display_label = false, display_client_name = true } --DOC_HIDE diff --git a/tests/examples/sequences/client/jump_to1.lua b/tests/examples/sequences/client/jump_to1.lua new file mode 100644 index 000000000..d69d4e3b0 --- /dev/null +++ b/tests/examples/sequences/client/jump_to1.lua @@ -0,0 +1,45 @@ + --DOC_GEN_IMAGE --DOC_NO_USAGE +local module = ... --DOC_HIDE +local awful = {tag = require("awful.tag"), layout = require("awful.layout")} --DOC_HIDE +local beautiful = require("beautiful") --DOC_HIDE +require("awful.ewmh") --DOC_HIDE +screen[1]._resize {x = 0, width = 160, height = 90} --DOC_HIDE +awful.tag({ "one", "two", "three" }, screen[1], awful.layout.suit.tile) --DOC_HIDE + +function awful.spawn(name, properties) --DOC_HIDE + client.gen_fake{class = name, name = name, x = 10, y=10, width = 60, height =50, tags = properties.tags} --DOC_HIDE +end --DOC_HIDE + +module.add_event("Spawn some apps", function() --DOC_HIDE + for tag_idx = 1, 3 do + for _ = 1, 3 do + awful.spawn("", {tags = {screen[1].tags[tag_idx]}}) + end + end + + client.get()[1].color = "#ff777733" --DOC_HIDE + +end) --DOC_HIDE + +--DOC_NEWLINE +module.display_tags() --DOC_HIDE + +module.add_event("Call `:jump_to()`, which will select tag #2", function() --DOC_HIDE + client.get()[6]:jump_to() + client.get()[1].color = beautiful.bg_normal --DOC_HIDE + client.get()[6].color = "#ff777733" --DOC_HIDE +end) --DOC_HIDE + +module.display_tags() --DOC_HIDE + +module.add_event("Call `:jump_to(true)`, which will select tag #2 and #3", function() --DOC_HIDE + --DOC_NEWLINE + client.get()[7]:jump_to(true) + client.get()[6].color = beautiful.bg_normal --DOC_HIDE + client.get()[7].color = "#ff777733" --DOC_HIDE +end) --DOC_HIDE + +module.display_tags() --DOC_HIDE + +module.execute { display_screen = false, display_clients = true , --DOC_HIDE + display_label = false, display_client_name = true } --DOC_HIDE diff --git a/tests/examples/sequences/client/kill1.lua b/tests/examples/sequences/client/kill1.lua new file mode 100644 index 000000000..84fd84fb6 --- /dev/null +++ b/tests/examples/sequences/client/kill1.lua @@ -0,0 +1,50 @@ + --DOC_GEN_IMAGE --DOC_HIDE_START --DOC_ASTERISK --DOC_NO_USAGE +local module = ... +require("ruled.client") +local awful = {tag = require("awful.tag"), layout = require("awful.layout")} +awful.placement = require("awful.placement") +require("awful.ewmh") +screen[1]:fake_resize(0, 0, 800, 480) +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.suit.tile) + +function awful.spawn(name) + client.gen_fake{class = name, name = name, x = 2094, y=10, width = 60, height =50, screen=screen[1]} +end + +--DOC_NEWLINE + +module.add_event("Spawn 5 clients in a `awful.layout.suit.tile` layout.", function() + --DOC_HIDE_END + -- Spawn a client on screen #3 + for i=1, 5 do + awful.spawn("Client #"..i) + end + + --DOC_NEWLINE + + client.get()[5]:activate {} + client.get()[5].color = "#ff777733" --DOC_HIDE + + --DOC_NEWLINE + --DOC_HIDE_START +end) + +module.display_tags() + +module.add_event("Kill the the 4th and 5th clients.", function() + --DOC_HIDE_END + local c4, c5 = client.get()[4], client.get()[5] + + --DOC_NEWLINE + -- Kill the clients. + c4:kill() + c5:kill() + --DOC_HIDE_START +end) + +module.display_tags() + +module.execute { display_screen = true , display_clients = true, + display_label = false, display_client_name = true, + display_mouse = false, +} diff --git a/tests/examples/sequences/client/minimize1.lua b/tests/examples/sequences/client/minimize1.lua new file mode 100644 index 000000000..ccaccc3b0 --- /dev/null +++ b/tests/examples/sequences/client/minimize1.lua @@ -0,0 +1,43 @@ + --DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_ASTERISK +local module = ... --DOC_HIDE +local awful = {tag = require("awful.tag"), layout = require("awful.layout")} --DOC_HIDE +require("awful.ewmh") --DOC_HIDE +screen[1]._resize {x = 0, width = 800, height = 600} --DOC_HIDE +awful.tag({ "one", "two", "three" }, screen[1], awful.layout.suit.tile) --DOC_HIDE + +function awful.spawn(name) --DOC_HIDE + client.gen_fake{class = name, name = name, x = 10, y=10, width = 60, height =50} --DOC_HIDE +end --DOC_HIDE + +module.add_event("Spawn some apps", function() --DOC_HIDE + for _ = 1, 3 do + awful.spawn("") + end + + client.get()[1].color = "#ff777733" --DOC_HIDE + +end) --DOC_HIDE + +--DOC_NEWLINE +module.display_tags() --DOC_HIDE + +module.add_event("Minimize the focused client", function() --DOC_HIDE + client.get()[1].minimized = true +end) --DOC_HIDE + +--DOC_NEWLINE +module.display_tags() --DOC_HIDE + +module.add_event("Raise and focus", function() --DOC_HIDE + -- That's the best way to unminimize if you also want to set the focus. + client.get()[1]:activate { + context = "unminimize", + raise = true, + } +end) --DOC_HIDE + + +module.display_tags() --DOC_HIDE + +module.execute { display_screen = true , display_clients = true , --DOC_HIDE + display_label = false, display_client_name = true } --DOC_HIDE diff --git a/tests/examples/sequences/client/move_to_screen1.lua b/tests/examples/sequences/client/move_to_screen1.lua new file mode 100644 index 000000000..61f4055c3 --- /dev/null +++ b/tests/examples/sequences/client/move_to_screen1.lua @@ -0,0 +1,54 @@ + --DOC_GEN_IMAGE --DOC_NO_USAGE +local module = ... --DOC_HIDE +require("ruled.client") --DOC_HIDE +local awful = {tag = require("awful.tag"), layout = require("awful.layout")} --DOC_HIDE +awful.placement = require("awful.placement") --DOC_HIDE +require("awful.ewmh") --DOC_HIDE +screen[1]:fake_resize(0, 0, 800, 480) --DOC_HIDE +screen.fake_add(830, 0, 800, 480).outputs = {["eVGA1"] = {mm_height=50, mm_width=80 }} --DOC_HIDE +screen.fake_add(1660, 0, 800, 480).outputs = {["DVI1" ] = {mm_height=50, mm_width=80 }} --DOC_HIDE +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.suit.corner.nw) --DOC_HIDE +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[2], awful.layout.suit.corner.nw) --DOC_HIDE +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[3], awful.layout.suit.corner.nw) --DOC_HIDE + +function awful.spawn(name) --DOC_HIDE + client.gen_fake{class = name, name = name, x = 2094, y=10, width = 60, height =50, screen=screen[1]} --DOC_HIDE +end --DOC_HIDE + + +--DOC_NEWLINE + +module.add_event("Spawn a client on screen #3", function() --DOC_HIDE + -- Move the mouse to screen 3 + mouse.coords {x = 100, y = 100 } + assert(mouse.screen == screen[1]) --DOC_HIDE + + --DOC_NEWLINE + + -- Spawn a client on screen #3 + awful.spawn("firefox") + + assert(client.get()[1].screen == screen[1]) --DOC_HIDE +end) --DOC_HIDE + +--DOC_NEWLINE +module.display_tags() --DOC_HIDE + +module.add_event("Move to screen #2", function() --DOC_HIDE + client.get()[1]:move_to_screen(screen[2]) +end) --DOC_HIDE + +--DOC_NEWLINE +module.display_tags() --DOC_HIDE + +module.add_event("Move to next screen", function() --DOC_HIDE + -- This will default to the next screen (by index). + client.get()[1]:move_to_screen() +end) --DOC_HIDE + +module.display_tags() --DOC_HIDE + +module.execute { display_screen = true , display_clients = true, --DOC_HIDE + display_label = false, display_client_name = true, --DOC_HIDE + display_mouse = true , --DOC_HIDE +} --DOC_HIDE diff --git a/tests/examples/sequences/client/move_to_tag1.lua b/tests/examples/sequences/client/move_to_tag1.lua new file mode 100644 index 000000000..4c59e4cd9 --- /dev/null +++ b/tests/examples/sequences/client/move_to_tag1.lua @@ -0,0 +1,33 @@ + --DOC_GEN_IMAGE --DOC_NO_USAGE +local module = ... --DOC_HIDE +local awful = {tag = require("awful.tag"), layout = require("awful.layout")} --DOC_HIDE +require("awful.ewmh") --DOC_HIDE +screen[1]._resize {x = 0, width = 160, height = 90} --DOC_HIDE +awful.tag({ "one", "two", "three" }, screen[1], awful.layout.suit.tile) --DOC_HIDE + +function awful.spawn(name, properties) --DOC_HIDE + client.gen_fake{class = name, name = name, x = 10, y=10, width = 60, height =50, tags = properties.tags} --DOC_HIDE +end --DOC_HIDE + +module.add_event("Spawn some apps", function() --DOC_HIDE + for tag_idx = 1, 3 do + for _ = 1, 3 do + awful.spawn("", {tags = {screen[1].tags[tag_idx]}}) + end + end + + client.get()[1].color = "#ff777733" --DOC_HIDE + +end) --DOC_HIDE + +--DOC_NEWLINE +module.display_tags() --DOC_HIDE + +module.add_event("Call `:move_to_tag()`", function() --DOC_HIDE + client.get()[1]:move_to_tag(screen[1].tags[2]) +end) --DOC_HIDE + +module.display_tags() --DOC_HIDE + +module.execute { display_screen = false, display_clients = true , --DOC_HIDE + display_label = false, display_client_name = true } --DOC_HIDE diff --git a/tests/examples/sequences/client/relative_move1.lua b/tests/examples/sequences/client/relative_move1.lua new file mode 100644 index 000000000..fd9ecec68 --- /dev/null +++ b/tests/examples/sequences/client/relative_move1.lua @@ -0,0 +1,61 @@ + --DOC_GEN_IMAGE --DOC_HIDE_START --DOC_NO_USAGE --DOC_GEN_OUTPUT +local module = ... +require("ruled.client") +local awful = {tag = require("awful.tag"), layout = require("awful.layout")} +awful.placement = require("awful.placement") +require("awful.ewmh") +screen[1]:fake_resize(0, 0, 800, 480) +awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.suit.tile) + +function awful.spawn(name) + client.gen_fake{class = name, name = name, x = 4, y=10, width = 60, height =50, screen=screen[1]} +end + +--DOC_NEWLINE + +module.add_event("Spawn a floating client.", function() + --DOC_HIDE_END + awful.spawn("") + + --DOC_NEWLINE + + client.get()[1].floating = true + + --DOC_NEWLINE + --DOC_HIDE_START +end) + +module.display_tags() + +module.add_event("Move it.", function() + --DOC_HIDE_END + client.get()[1]:relative_move(100, 100) + --DOC_NEWLINE + + local geo = client.get()[1]:geometry() + print("Client geometry:", geo.x, geo.y, geo.width, geo.height) + --DOC_NEWLINE + + --DOC_HIDE_START +end) + +module.display_tags() + +module.add_event("Resize it.", function() + --DOC_HIDE_END + client.get()[1]:relative_move(nil, nil, 100, 100) + --DOC_NEWLINE + + local geo = client.get()[1]:geometry() + print("Client geometry:", geo.x, geo.y, geo.width, geo.height) + + --DOC_HIDE_START +end) + +module.display_tags() + + +module.execute { display_screen = true , display_clients = true, + display_label = false, display_client_name = true, + display_mouse = false, +} diff --git a/tests/examples/sequences/client/relative_move1.output.txt b/tests/examples/sequences/client/relative_move1.output.txt new file mode 100644 index 000000000..3bdf3709f --- /dev/null +++ b/tests/examples/sequences/client/relative_move1.output.txt @@ -0,0 +1,2 @@ +Client geometry: 110 110 120 100 +Client geometry: 220 220 220 200 diff --git a/tests/examples/sequences/client/tags1.lua b/tests/examples/sequences/client/tags1.lua new file mode 100644 index 000000000..e8f89dbef --- /dev/null +++ b/tests/examples/sequences/client/tags1.lua @@ -0,0 +1,42 @@ + --DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_GEN_OUTPUT --DOC_ASTERISK +local module = ... --DOC_HIDE +local awful = {tag = require("awful.tag"), layout = require("awful.layout")} --DOC_HIDE +require("awful.ewmh") --DOC_HIDE +screen[1]._resize {x = 0, width = 160, height = 90} --DOC_HIDE +awful.tag({ "one", "two", "three" }, screen[1], awful.layout.suit.tile) --DOC_HIDE + +function awful.spawn(name, properties) --DOC_HIDE + client.gen_fake{class = name, name = name, x = 10, y=10, width = 60, height =50, tags = properties.tags} --DOC_HIDE +end --DOC_HIDE + +module.add_event("Spawn some apps", function() --DOC_HIDE + for tag_idx = 1, 3 do + for _ = 1, 3 do + awful.spawn("", {tags = {screen[1].tags[tag_idx]}}) + end + end + + client.get()[1].color = "#ff777733" --DOC_HIDE + +end) --DOC_HIDE + +--DOC_NEWLINE +module.display_tags() --DOC_HIDE + +module.add_event("Set the tags", function() --DOC_HIDE + client.get()[1]:tags { + screen[1].tags[2], + screen[1].tags[3] + } + + --DOC_NEWLINE + -- It also works to get the tags. + for _, t in ipairs(client.get()[1]:tags()) do + print("Tag:", t.index, t.name) + end +end) --DOC_HIDE + +module.display_tags() --DOC_HIDE + +module.execute { display_screen = false, display_clients = true , --DOC_HIDE + display_label = false, display_client_name = true } --DOC_HIDE diff --git a/tests/examples/sequences/client/tags1.output.txt b/tests/examples/sequences/client/tags1.output.txt new file mode 100644 index 000000000..70d4b215c --- /dev/null +++ b/tests/examples/sequences/client/tags1.output.txt @@ -0,0 +1,2 @@ +Tag: 2 two +Tag: 3 three diff --git a/tests/examples/sequences/client/to_selected_tags1.lua b/tests/examples/sequences/client/to_selected_tags1.lua new file mode 100644 index 000000000..a32d46e6d --- /dev/null +++ b/tests/examples/sequences/client/to_selected_tags1.lua @@ -0,0 +1,40 @@ + --DOC_GEN_IMAGE --DOC_NO_USAGE +local module = ... --DOC_HIDE +local awful = {tag = require("awful.tag"), layout = require("awful.layout")} --DOC_HIDE +require("awful.ewmh") --DOC_HIDE +screen[1]._resize {x = 0, width = 160, height = 90} --DOC_HIDE +awful.tag({ "one", "two", "three", "four" }, screen[1], awful.layout.suit.tile) --DOC_HIDE + +function awful.spawn(name) --DOC_HIDE + client.gen_fake{class = name, name = name, x = 10, y=10, width = 60, height =50} --DOC_HIDE +end --DOC_HIDE + +module.add_event("Spawn some apps", function() --DOC_HIDE + awful.spawn("Client") + + --DOC_NEWLINE + + client.get()[1].color = "#ff777733" --DOC_HIDE + + + screen[1].tags[1].selected = false + screen[1].tags[2].selected = true + screen[1].tags[3].selected = true +end) --DOC_HIDE + +--DOC_NEWLINE +module.display_tags() --DOC_HIDE + +module.add_event("Call `:to_selected_tags()`", function() --DOC_HIDE + -- Deselect all tags, otherwise it will do nothing. + client.get()[1]:tags{} + + --DOC_NEWLINE + + client.get()[1]:to_selected_tags() +end) --DOC_HIDE + +module.display_tags() --DOC_HIDE + +module.execute { display_screen = false, display_clients = true , --DOC_HIDE + display_label = false, display_client_name = true } --DOC_HIDE diff --git a/tests/examples/sequences/client/toggle_tag1.lua b/tests/examples/sequences/client/toggle_tag1.lua new file mode 100644 index 000000000..c06ce39c9 --- /dev/null +++ b/tests/examples/sequences/client/toggle_tag1.lua @@ -0,0 +1,33 @@ + --DOC_GEN_IMAGE --DOC_NO_USAGE +local module = ... --DOC_HIDE +local awful = {tag = require("awful.tag"), layout = require("awful.layout")} --DOC_HIDE +require("awful.ewmh") --DOC_HIDE +screen[1]._resize {x = 0, width = 160, height = 90} --DOC_HIDE +awful.tag({ "one", "two", "three" }, screen[1], awful.layout.suit.tile) --DOC_HIDE + +function awful.spawn(name, properties) --DOC_HIDE + client.gen_fake{class = name, name = name, x = 10, y=10, width = 60, height =50, tags = properties.tags} --DOC_HIDE +end --DOC_HIDE + +module.add_event("Spawn some apps", function() --DOC_HIDE + for tag_idx = 1, 3 do + for _ = 1, 3 do + awful.spawn("", {tags = {screen[1].tags[tag_idx]}}) + end + end + + client.get()[1].color = "#ff777733" --DOC_HIDE + +end) --DOC_HIDE + +--DOC_NEWLINE +module.display_tags() --DOC_HIDE + +module.add_event("Call `:toggle_tag(screen[1].tags[2])`", function() --DOC_HIDE + client.get()[1]:toggle_tag(screen[1].tags[2]) +end) --DOC_HIDE + +module.display_tags() --DOC_HIDE + +module.execute { display_screen = false, display_clients = true , --DOC_HIDE + display_label = false, display_client_name = true } --DOC_HIDE diff --git a/tests/examples/sequences/client/width1.lua b/tests/examples/sequences/client/width1.lua new file mode 100644 index 000000000..3758c127d --- /dev/null +++ b/tests/examples/sequences/client/width1.lua @@ -0,0 +1,29 @@ + --DOC_GEN_IMAGE --DOC_NO_USAGE +local module = ... --DOC_HIDE +local awful = {tag = require("awful.tag"), layout = require("awful.layout")} --DOC_HIDE +require("awful.ewmh") --DOC_HIDE +screen[1]._resize {x = 0, width = 160, height = 90} --DOC_HIDE +awful.tag({ "one", "two", "three" }, screen[1], awful.layout.suit.tile) --DOC_HIDE + +function awful.spawn(name) --DOC_HIDE + client.gen_fake{class = name, name = name, x = 10, y=10, width = 60, height =50, floating = true} --DOC_HIDE +end --DOC_HIDE + +module.add_event("Spawn a client", function() --DOC_HIDE + awful.spawn("") --DOC_HIDE + + client.get()[1].color = "#ff777733" --DOC_HIDE + +end) --DOC_HIDE + +--DOC_NEWLINE +module.display_tags() --DOC_HIDE + +module.add_event("Change the `width` property", function() --DOC_HIDE + client.focus.width = 100 +end) --DOC_HIDE + +module.display_tags() --DOC_HIDE + +module.execute { display_screen = false, display_clients = true , --DOC_HIDE + display_label = false, display_client_name = true } --DOC_HIDE diff --git a/tests/examples/sequences/client/x1.lua b/tests/examples/sequences/client/x1.lua new file mode 100644 index 000000000..58a2b0810 --- /dev/null +++ b/tests/examples/sequences/client/x1.lua @@ -0,0 +1,29 @@ + --DOC_GEN_IMAGE --DOC_NO_USAGE +local module = ... --DOC_HIDE +local awful = {tag = require("awful.tag"), layout = require("awful.layout")} --DOC_HIDE +require("awful.ewmh") --DOC_HIDE +screen[1]._resize {x = 0, width = 160, height = 90} --DOC_HIDE +awful.tag({ "one", "two", "three" }, screen[1], awful.layout.suit.tile) --DOC_HIDE + +function awful.spawn(name) --DOC_HIDE + client.gen_fake{class = name, name = name, x = 10, y=10, width = 60, height =50, floating = true} --DOC_HIDE +end --DOC_HIDE + +module.add_event("Spawn a client", function() --DOC_HIDE + awful.spawn("") --DOC_HIDE + + client.get()[1].color = "#ff777733" --DOC_HIDE + +end) --DOC_HIDE + +--DOC_NEWLINE +module.display_tags() --DOC_HIDE + +module.add_event("Change the `x` property", function() --DOC_HIDE + client.focus.x = 100 +end) --DOC_HIDE + +module.display_tags() --DOC_HIDE + +module.execute { display_screen = false, display_clients = true , --DOC_HIDE + display_label = false, display_client_name = true } --DOC_HIDE diff --git a/tests/examples/sequences/client/y1.lua b/tests/examples/sequences/client/y1.lua new file mode 100644 index 000000000..46fda5bb6 --- /dev/null +++ b/tests/examples/sequences/client/y1.lua @@ -0,0 +1,29 @@ + --DOC_GEN_IMAGE --DOC_NO_USAGE +local module = ... --DOC_HIDE +local awful = {tag = require("awful.tag"), layout = require("awful.layout")} --DOC_HIDE +require("awful.ewmh") --DOC_HIDE +screen[1]._resize {x = 0, width = 160, height = 90} --DOC_HIDE +awful.tag({ "one", "two", "three" }, screen[1], awful.layout.suit.tile) --DOC_HIDE + +function awful.spawn(name) --DOC_HIDE + client.gen_fake{class = name, name = name, x = 10, y=10, width = 60, height =50, floating = true} --DOC_HIDE +end --DOC_HIDE + +module.add_event("Spawn a client", function() --DOC_HIDE + awful.spawn("") --DOC_HIDE + + client.get()[1].color = "#ff777733" --DOC_HIDE + +end) --DOC_HIDE + +--DOC_NEWLINE +module.display_tags() --DOC_HIDE + +module.add_event("Change the `y` property", function() --DOC_HIDE + client.focus.y = 50 +end) --DOC_HIDE + +module.display_tags() --DOC_HIDE + +module.execute { display_screen = false, display_clients = true , --DOC_HIDE + display_label = false, display_client_name = true } --DOC_HIDE diff --git a/tests/examples/sequences/template.lua b/tests/examples/sequences/template.lua index 73d605049..4dbf16ab6 100644 --- a/tests/examples/sequences/template.lua +++ b/tests/examples/sequences/template.lua @@ -245,10 +245,18 @@ end local function get_all_tag_clients(t) local s = t.screen - local clients = gtable.clone(t:clients(), false) + local all_clients = gtable.clone(t:clients(), false) + + local clients = {} + + for _, c in ipairs(all_clients) do + if not c.minimized then + table.insert(clients, c) + end + end for _, c in ipairs(s.clients) do - if c.sticky then + if c.sticky and not c.minimized then if not gtable.hasitem(clients, c) then table.insert(clients, c) end @@ -304,6 +312,7 @@ local function fake_arrange(tag) for _, geo_src in ipairs {param.geometries, flt } do for c, geo in pairs(geo_src) do geo.c = geo.c or c + geo.color = geo.c.color table.insert(ret, geo) end end @@ -332,7 +341,7 @@ local function gen_fake_clients(tag, args) local y = (geom.y*h)/sgeo.height local width = (geom.width*w)/sgeo.width local height = (geom.height*h)/sgeo.height - cr:set_source(color(geom.c.color or beautiful.bg_normal)) + cr:set_source(color(geom.color or beautiful.bg_normal)) cr:rectangle(x,y,width,height) cr:fill_preserve() cr:set_source(color(geom.c.border_color or beautiful.border_color)) From 62685c661daa799117f54239e1412dfc4129930d Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sat, 16 Oct 2021 22:19:32 -0700 Subject: [PATCH 15/18] doc: Modernize the tag documentation... again... The last time this page had a refresh was in parallel with another massive whole-doc project. Thus, this page still had older conventions which everything else had already removed. --- lib/awful/tag.lua | 120 +++++++++++++++++----------------------------- objects/tag.c | 21 +++----- 2 files changed, 49 insertions(+), 92 deletions(-) diff --git a/lib/awful/tag.lua b/lib/awful/tag.lua index f30a769e5..fcd8f1b4f 100644 --- a/lib/awful/tag.lua +++ b/lib/awful/tag.lua @@ -147,13 +147,9 @@ end -- -- The index is the position as shown in the `awful.widget.taglist`. -- --- **Signal:** --- --- * *property::index* --- -- @property index --- @param integer --- @treturn number The tag index. +-- @tparam integer index +-- @propemits false false function tag.object.set_index(self, idx) local scr = get_screen(tag.getproperty(self, "screen")) @@ -225,7 +221,7 @@ end -- @DOC_sequences_tag_swap_EXAMPLE@ -- -- @method swap --- @param tag2 The second tag +-- @tparam tag tag2 The second tag -- @see client.swap function tag.object.swap(self, tag2) local idx1, idx2 = tag.object.get_index(self), tag.object.get_index(tag2) @@ -265,8 +261,8 @@ end -- }) -- -- @constructorfct awful.tag.add --- @param name The tag name, a string --- @param props The tags initial properties, a table +-- @tparam string name The tag name, a string +-- @tparam[opt=nil] table|nil props The tags initial properties, a table -- @return The created tag -- @see tag.delete function tag.add(name, props) @@ -338,8 +334,8 @@ end --- Find a suitable fallback tag. -- @staticfct awful.tag.find_fallback --- @param screen The screen to look for a tag on. [awful.screen.focused()] --- @param invalids A table of tags we consider unacceptable. [selectedlist(scr)] +-- @tparam screen screen The screen to look for a tag on. [awful.screen.focused()] +-- @tparam[opt=nil] table|nil invalids A table of tags considered unacceptable. [selectedlist(scr)] function tag.find_fallback(screen, invalids) local scr = screen or ascreen.focused() local t = invalids or scr.selected_tags @@ -484,7 +480,7 @@ end --- Update the tag history. -- @staticfct awful.tag.history.update --- @param obj Screen object. +-- @tparam screen obj Screen object. function tag.history.update(obj) local s = get_screen(obj) local curtags = s.selected_tags @@ -525,8 +521,8 @@ end --- Revert tag history. -- @staticfct awful.tag.history.restore --- @param screen The screen. --- @param idx Index in history. Defaults to "previous" which is a special index +-- @tparam screen screen The screen. +-- @tparam number idx Index in history. Defaults to "previous" which is a special index -- toggling between last two selected sets of tags. Number (eg 1) will go back -- to the given index in history. function tag.history.restore(screen, idx) @@ -597,12 +593,9 @@ end --- The tag screen. -- --- **Signal:** --- --- * *property::screen* --- -- @property screen --- @param screen +-- @tparam screen screen +-- @propemits false false -- @see screen function tag.object.set_screen(t, s) @@ -720,13 +713,10 @@ end -- -- @DOC_screen_mwfact2_EXAMPLE@ -- --- **Signal:** --- --- * *property::mwfact* (deprecated) --- * *property::master_width_factor* --- -- @property master_width_factor --- @param number Between 0 and 1 +-- @tparam number master_width_factor Between 0 and 1 +-- @emits property::mwfact When the value changes (deprecated). +-- @emits property::master_width_factor When the value changes. -- @see master_count -- @see column_count -- @see master_fill_policy @@ -761,8 +751,8 @@ end --- Increase master width factor. -- @staticfct awful.tag.incmwfact -- @see master_width_factor --- @param add Value to add to master width factor. --- @param t The tag to modify, if null tag.selected() is used. +-- @tparam number add Value to add to master width factor. +-- @tparam tag t The tag to modify, if null tag.selected() is used. function tag.incmwfact(add, t) t = t or t or ascreen.focused().selected_tag tag.object.set_master_width_factor(t, tag.object.get_master_width_factor(t) + add) @@ -841,13 +831,10 @@ end -- -- @DOC_screen_taglayout_EXAMPLE@ -- --- **Signal:** --- --- * *property::layout* --- -- @property layout --- @see awful.tag.layouts -- @tparam layout|function layout A layout table or a constructor function +-- @propemits false false +-- @see awful.tag.layouts -- @return The layout --- The (proposed) list of available layouts for this tag. @@ -862,7 +849,7 @@ end -- front of the list. -- -- @property layouts --- @param table +-- @tparam table layouts -- @request tag layouts awful granted When the `layouts` property is first called -- and there is no layouts, then that signal is called. -- @see awful.layout.layouts @@ -1055,12 +1042,9 @@ end -- As you can see, the "Volatile" tag has been automatically discarded while -- the "Non-volatile" tag is still there (but with zero clients). -- --- **Signal:** --- --- * *property::volatile* --- -- @property volatile --- @param boolean +-- @tparam boolean volatile +-- @propemits false false -- @see delete -- Volatile accessors are implicit @@ -1107,12 +1091,9 @@ end -- -- @DOC_screen_gaps2_EXAMPLE@ -- --- **Signal:** --- --- * *property::useless_gap* --- -- @property gap --- @param number The value has to be greater than zero. +-- @tparam number gap The value has to be greater than zero. +-- @emits property::useless_gap When the gap changes. -- @see gap_single_client -- @see awful.tag.incgap @@ -1142,8 +1123,8 @@ end --- Increase the spacing between clients -- @staticfct awful.tag.incgap -- @see gap --- @param add Value to add to the spacing between clients --- @param t The tag to modify, if null tag.selected() is used. +-- @tparam number add Value to add to the spacing between clients +-- @tparam tag t The tag to modify, if null tag.selected() is used. function tag.incgap(add, t) t = t or t or ascreen.focused().selected_tag tag.object.set_gap(t, tag.object.get_gap(t) + add) @@ -1171,12 +1152,9 @@ end -- -- @DOC_screen_gap_single_client_false_EXAMPLE@ -- --- **Signal:** --- --- * *property::gap\_single\_client* --- -- @property gap_single_client --- @param boolean Enable gaps for a single client +-- @tparam boolean gap_single_client Enable gaps for a single client +-- @propemits false false -- @see awful.tag.incgap function tag.object.set_gap_single_client(t, gap_single_client) @@ -1246,12 +1224,9 @@ end -- The remaining space that would have been used for the second column is -- redistributed on both side. -- --- **Signal:** --- --- * *property::master_fill_policy* --- -- @property master_fill_policy --- @param string "expand" or "master_width_factor" +-- @tparam string master_fill_policy "expand" or "master_width_factor" +-- @propemits false false -- @see awful.tag.togglemfpol function tag.object.get_master_fill_policy(t) @@ -1315,13 +1290,10 @@ end -- -- @DOC_sequences_tag_master_count_EXAMPLE@ -- --- **Signal:** --- --- * *property::nmaster* (deprecated) --- * *property::master_count* --- -- @property master_count --- @param integer nmaster Only positive values are accepted +-- @tparam integer master_count nmaster Only positive values are accepted +-- @emits property::nmaster Deprecated. +-- @emits property::master_count When the value changes. -- @see awful.tag.incnmaster function tag.object.set_master_count(t, nmaster) @@ -1337,7 +1309,7 @@ function tag.object.get_master_count(t) or defaults.master_count end ---- +--- The number of master clients. -- @deprecated awful.tag.setnmaster -- @see master_count -- @param nmaster The number of master windows. @@ -1362,8 +1334,8 @@ end --- Increase the number of master windows. -- @staticfct awful.tag.incnmaster -- @see master_count --- @param add Value to add to number of master windows. --- @param[opt] t The tag to modify, if null tag.selected() is used. +-- @tparam number add Value to add to number of master windows. +-- @tparam[opt] tag t The tag to modify, if null tag.selected() is used. -- @tparam[opt=false] boolean sensible Limit nmaster based on the number of -- visible tiled windows? function tag.incnmaster(add, t, sensible) @@ -1392,12 +1364,9 @@ end -- -- @DOC_wibox_awidget_taglist_icon_EXAMPLE@ -- --- **Signal:** --- --- * *property::icon* --- -- @property icon -- @tparam path|surface icon The icon +-- @propemits false false -- @see awful.widget.taglist -- @see gears.surface @@ -1407,7 +1376,7 @@ end -- @deprecated awful.tag.seticon -- @see icon -- @param icon the icon to set, either path or image object --- @param _tag the tag +-- @tparam tag tag the tag function tag.seticon(icon, _tag) gdebug.deprecate("Use t.icon = icon instead of awful.tag.seticon", {deprecated_in=4}) @@ -1418,7 +1387,7 @@ end --- Get the tag icon -- @deprecated awful.tag.geticon -- @see icon --- @param _tag the tag +-- @tparam tag tag the tag function tag.geticon(_tag) gdebug.deprecate("Use t.icon instead of awful.tag.geticon", {deprecated_in=4}) @@ -1436,13 +1405,10 @@ end -- -- @DOC_sequences_tag_column_count_EXAMPLE@ -- --- **Signal:** --- --- * *property::ncol* (deprecated) --- * *property::column_count* --- -- @property column_count -- @tparam integer ncol Has to be greater than 1 +-- @emits property::ncol Deprecated. +-- @emits property::column_count When the value changes. -- @see awful.tag.incncol function tag.object.set_column_count(t, ncol) @@ -1486,8 +1452,8 @@ end --- Increase number of column windows. -- @staticfct awful.tag.incncol --- @param add Value to add to number of column windows. --- @param[opt] t The tag to modify, if null tag.selected() is used. +-- @tparam number add Value to add to number of column windows. +-- @tparam[opt] tag t The tag to modify, if null tag.selected() is used. -- @tparam[opt=false] boolean sensible Limit column_count based on the number -- of visible tiled windows? function tag.incncol(add, t, sensible) diff --git a/objects/tag.c b/objects/tag.c index ffd28d41b..80d74b6ea 100644 --- a/objects/tag.c +++ b/objects/tag.c @@ -261,12 +261,9 @@ lua_class_t tag_class; * * @DOC_sequences_tag_name_EXAMPLE@ * - * **Signal:** - * - * * *property::name* - * * @property name - * @param string + * @tparam string name + * @propemits false false */ /** @@ -274,23 +271,17 @@ lua_class_t tag_class; * * @DOC_sequences_tag_selected_EXAMPLE@ * - * **Signal:** - * - * * *property::selected* - * * @property selected - * @param boolean + * @tparam boolean selected + * @propemits false false */ /** * True if the tag is active and can be used. * - * **Signal:** - * - * * *property::activated* - * * @property activated - * @param boolean + * @tparam boolean activated + * @propemits false false */ /** Get the number of instances. From ae711580936fd2bb8ad82e10ce7a4145ff603774 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 17 Oct 2021 19:22:38 -0700 Subject: [PATCH 16/18] 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 From cbec148540ec9e69195f4c37fe34b8692bde2b49 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 17 Oct 2021 19:55:20 -0700 Subject: [PATCH 17/18] doc: Make sure all client.focus functions are in the same section. Some were in the @staticfct and some in the @function sections. --- lib/awful/client.lua | 17 +---------------- lib/awful/client/focus.lua | 20 ++++++++++++++++++++ 2 files changed, 21 insertions(+), 16 deletions(-) diff --git a/lib/awful/client.lua b/lib/awful/client.lua index 1f3805402..71acec050 100644 --- a/lib/awful/client.lua +++ b/lib/awful/client.lua @@ -1857,12 +1857,7 @@ end -- Connect to "focus" signal, and allow to disable tracking. do local disabled_count = 1 - --- Disable history tracking. - -- - -- See `awful.client.focus.history.enable_tracking` to enable it again. - -- @treturn int The internal value of `disabled_count` (calls to this - -- function without calling `awful.client.focus.history.enable_tracking`). - -- @staticfct awful.client.focus.history.disable_tracking + function client.focus.history.disable_tracking() disabled_count = disabled_count + 1 if disabled_count == 1 then @@ -1871,12 +1866,6 @@ do return disabled_count end - --- Enable history tracking. - -- - -- This is the default, but can be disabled - -- through `awful.client.focus.history.disable_tracking`. - -- @treturn boolean True if history tracking has been enabled. - -- @staticfct awful.client.focus.history.enable_tracking function client.focus.history.enable_tracking() assert(disabled_count > 0) disabled_count = disabled_count - 1 @@ -1886,10 +1875,6 @@ do return disabled_count == 0 end - --- Is history tracking enabled? - -- @treturn bool True if history tracking is enabled. - -- @treturn int The number of times that tracking has been disabled. - -- @staticfct awful.client.focus.history.is_enabled function client.focus.history.is_enabled() return disabled_count == 0, disabled_count end diff --git a/lib/awful/client/focus.lua b/lib/awful/client/focus.lua index 487d7adcc..7b1eb39c7 100644 --- a/lib/awful/client/focus.lua +++ b/lib/awful/client/focus.lua @@ -218,6 +218,26 @@ function focus.global_bydirection(dir, c, stacked) end end +--- Is history tracking enabled? +-- @treturn bool True if history tracking is enabled. +-- @treturn int The number of times that tracking has been disabled. +-- @function awful.client.focus.history.is_enabled + +--- Enable history tracking. +-- +-- This is the default, but can be disabled +-- through `awful.client.focus.history.disable_tracking`. +-- @treturn boolean True if history tracking has been enabled. +-- @function awful.client.focus.history.enable_tracking + +--- Disable history tracking. +-- +-- See `awful.client.focus.history.enable_tracking` to enable it again. +-- @treturn int The internal value of `disabled_count` (calls to this +-- function without calling `awful.client.focus.history.enable_tracking`). +-- @function awful.client.focus.history.disable_tracking + + return focus -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 From b2603f6a86c8c39917f91c37233cd852500baef4 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Mon, 18 Oct 2021 14:33:14 -0700 Subject: [PATCH 18/18] doc: Add images for awful.client.* functions. --- lib/awful/client.lua | 18 +++++ lib/awful/client/focus.lua | 6 ++ tests/examples/sequences/client/cycle1.lua | 62 ++++++++++++++ .../sequences/client/cycle1.output.txt | 0 .../sequences/client/focus_bydirection1.lua | 78 ++++++++++++++++++ .../sequences/client/focus_bydirection2.lua | 78 ++++++++++++++++++ .../sequences/client/focus_byidx1.lua | 81 +++++++++++++++++++ .../sequences/client/focus_byidx1.output.txt | 5 ++ .../sequences/client/jump_to_urgent1.lua | 42 ++++++++++ tests/examples/sequences/client/restore1.lua | 67 +++++++++++++++ .../sequences/client/swap_bydirection1.lua | 68 ++++++++++++++++ .../sequences/client/swap_bydirection2.lua | 68 ++++++++++++++++ .../examples/sequences/client/swap_byidx1.lua | 70 ++++++++++++++++ .../sequences/client/swap_byidx1.output.txt | 5 ++ tests/examples/sequences/template.lua | 5 ++ 15 files changed, 653 insertions(+) create mode 100644 tests/examples/sequences/client/cycle1.lua create mode 100644 tests/examples/sequences/client/cycle1.output.txt create mode 100644 tests/examples/sequences/client/focus_bydirection1.lua create mode 100644 tests/examples/sequences/client/focus_bydirection2.lua create mode 100644 tests/examples/sequences/client/focus_byidx1.lua create mode 100644 tests/examples/sequences/client/focus_byidx1.output.txt create mode 100644 tests/examples/sequences/client/jump_to_urgent1.lua create mode 100644 tests/examples/sequences/client/restore1.lua create mode 100644 tests/examples/sequences/client/swap_bydirection1.lua create mode 100644 tests/examples/sequences/client/swap_bydirection2.lua create mode 100644 tests/examples/sequences/client/swap_byidx1.lua create mode 100644 tests/examples/sequences/client/swap_byidx1.output.txt diff --git a/lib/awful/client.lua b/lib/awful/client.lua index 71acec050..16085ab49 100644 --- a/lib/awful/client.lua +++ b/lib/awful/client.lua @@ -257,6 +257,7 @@ end -- @tparam[opt] client sel The client. -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom) -- @treturn[opt] client|nil A client, or nil if no client is available. +-- @see client.get -- -- @usage -- focus the next window in the index -- awful.client.next(1) @@ -288,6 +289,11 @@ end --- Swap a client with another client in the given direction. -- +-- This will not cross the screen boundary. If you want this behavior, use +-- `awful.client.swap.global_bydirection`. +-- +-- @DOC_sequences_client_swap_bydirection1_EXAMPLE@ +-- -- @staticfct awful.client.swap.bydirection -- @tparam string dir The direction, can be either "up", "down", "left" or "right". -- @tparam[opt=focused] client c The client. @@ -317,6 +323,9 @@ end --- Swap a client with another client in the given direction. -- -- Swaps across screens. +-- +-- @DOC_sequences_client_swap_bydirection2_EXAMPLE@ +-- -- @staticfct awful.client.swap.global_bydirection -- @tparam string dir The direction, can be either "up", "down", "left" or "right". -- @tparam[opt] client sel The client. @@ -358,6 +367,8 @@ end --- Swap a client by its relative index. -- +-- @DOC_sequences_client_swap_byidx1_EXAMPLE@ +-- -- @staticfct awful.client.swap.byidx -- @tparam integer i The index. -- @tparam[opt] client c The client, otherwise focused one is used. @@ -379,6 +390,8 @@ end -- This will swap the client from one position to the next -- in the layout. -- +-- @DOC_sequences_client_cycle1_EXAMPLE@ +-- -- @staticfct awful.client.cycle -- @tparam boolean clockwise True to cycle clients clockwise. -- @tparam[opt] screen s The screen where to cycle clients. @@ -1068,6 +1081,9 @@ end --- Restore (=unminimize) a random client. +-- +-- @DOC_sequences_client_restore1_EXAMPLE@ +-- -- @staticfct awful.client.restore -- @tparam screen s The screen to use. -- @treturn client The restored client if some client was restored, otherwise nil. @@ -1804,6 +1820,8 @@ end) --- Jump to the client that received the urgent hint first. -- +-- @DOC_sequences_client_jump_to_urgent1_EXAMPLE@ +-- -- @staticfct awful.client.urgent.jumpto -- @tparam bool|function merge If true then merge tags (select the client's -- first tag additionally) when the client is not visible. diff --git a/lib/awful/client/focus.lua b/lib/awful/client/focus.lua index 7b1eb39c7..1b97674de 100644 --- a/lib/awful/client/focus.lua +++ b/lib/awful/client/focus.lua @@ -57,6 +57,8 @@ end --- Focus a client by its relative index. -- +-- @DOC_sequences_client_focus_byidx1_EXAMPLE@ +-- -- @function awful.client.focus.byidx -- @param i The index. -- @tparam[opt] client c The client. @@ -157,6 +159,8 @@ end --- Focus a client by the given direction. -- +-- @DOC_sequences_client_focus_bydirection1_EXAMPLE@ +-- -- @tparam string dir The direction, can be either -- `"up"`, `"down"`, `"left"` or `"right"`. -- @tparam[opt] client c The client. @@ -185,6 +189,8 @@ end --- Focus a client by the given direction. Moves across screens. -- +-- @DOC_sequences_client_focus_bydirection2_EXAMPLE@ +-- -- @param dir The direction, can be either "up", "down", "left" or "right". -- @tparam[opt] client c The client. -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom) diff --git a/tests/examples/sequences/client/cycle1.lua b/tests/examples/sequences/client/cycle1.lua new file mode 100644 index 000000000..60e350494 --- /dev/null +++ b/tests/examples/sequences/client/cycle1.lua @@ -0,0 +1,62 @@ + --DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_START +local module = ... +local awful = {tag = require("awful.tag"), layout = require("awful.layout"), + client = require("awful.client"), screen = require("awful.screen")} +local beautiful = require("beautiful") +require("awful.ewmh") +screen[1]._resize {x = 0, width = 640, height = 360} +awful.tag({ "one", "two", "three" }, screen[1], awful.layout.suit.tile) + +function awful.spawn(name, properties) + client.gen_fake{class = name, name = name, x = 10, y=10, width = 60, height =50, tags = properties.tags} +end + +local function color_focus() + for _, c in ipairs(client.get()) do + c.color = c.active and "#ff777733" or beautiful.bg_normal + end +end + +module.add_event("Spawn some apps", function() + for tag_idx = 1, 3 do + for i = 1, 3 do + awful.spawn("c"..((tag_idx-1)*3+i), {tags = {screen[1].tags[tag_idx]}}) + end + end + + client.get()[2]:activate{} + + color_focus() +end) + +--DOC_NEWLINE +module.display_tags() + +module.add_event('Call `cycle`', function() + --DOC_HIDE_END + + --DOC_NEWLINE + awful.client.cycle(true, awful.screen.focused(), true) + + --DOC_HIDE_START + color_focus() +end) + + +--DOC_NEWLINE +module.display_tags() + +module.add_event('Call `cycle` again', function() + --DOC_HIDE_END + + awful.client.cycle(true, awful.screen.focused(), true) + + --DOC_HIDE_START + color_focus() +end) + + +module.display_tags() + +module.execute { display_screen = true , display_clients = true , + display_label = false, display_client_name = true } diff --git a/tests/examples/sequences/client/cycle1.output.txt b/tests/examples/sequences/client/cycle1.output.txt new file mode 100644 index 000000000..e69de29bb diff --git a/tests/examples/sequences/client/focus_bydirection1.lua b/tests/examples/sequences/client/focus_bydirection1.lua new file mode 100644 index 000000000..b2d4ee991 --- /dev/null +++ b/tests/examples/sequences/client/focus_bydirection1.lua @@ -0,0 +1,78 @@ + --DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_START +local module = ... +local awful = {tag = require("awful.tag"), layout = require("awful.layout"), + client = require("awful.client"), screen = require("awful.screen")} +require("awful.ewmh") +local beautiful = require("beautiful") +screen[1]._resize {x = 0, width = 640, height = 360} +screen.fake_add(660, 0, 640, 360) +awful.tag({ "one", "two", "three" }, screen[1], awful.layout.suit.tile) +awful.tag({ "one", "two", "three" }, screen[2], awful.layout.suit.tile) + +local function color_focus() + for _, c in ipairs(client.get()) do + c.color = c.active and "#ff777733" or beautiful.bg_normal + end +end + +function awful.spawn(name, properties) + client.gen_fake{class = name, name = name, x = 10, y=10, width = 60, height =50, screen = properties.screen} +end + +module.add_event("Spawn some apps", function() + for s in screen do + for i = 1, 4 do + awful.spawn("c"..((s.index -1)*4 + i), {screen = s}) + end + end + + client.focus = client.get()[3] + client.focus.color = "#ff777733" +end) + +module.display_tags() + +module.add_event('Call `focus.bydirection` to the top', function() + --DOC_HIDE_END + + --DOC_NEWLINE + -- It will go up in the same column. + awful.client.focus.bydirection("up", client.focus) + + --DOC_HIDE_START + color_focus() +end) + + +--DOC_NEWLINE +module.display_tags() + +module.add_event('Call `focus.bydirection` to the right', function() + --DOC_HIDE_END + + --DOC_NEWLINE + -- Nothing happens because it cannot change screen. + awful.client.focus.bydirection("right", client.focus) + + --DOC_HIDE_START + color_focus() +end) + +--DOC_NEWLINE +module.display_tags() + +module.add_event('Call `focus.bydirection` to the left', function() + --DOC_HIDE_END + + --DOC_NEWLINE + -- Moves to the first column. + awful.client.focus.bydirection("left", client.focus) + + --DOC_HIDE_START + color_focus() +end) + +module.display_tags() + +module.execute { display_screen = true , display_clients = true , + display_label = false, display_client_name = true } diff --git a/tests/examples/sequences/client/focus_bydirection2.lua b/tests/examples/sequences/client/focus_bydirection2.lua new file mode 100644 index 000000000..f11e481cb --- /dev/null +++ b/tests/examples/sequences/client/focus_bydirection2.lua @@ -0,0 +1,78 @@ + --DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_START +local module = ... +local awful = {tag = require("awful.tag"), layout = require("awful.layout"), + client = require("awful.client"), screen = require("awful.screen")} +require("awful.ewmh") +local beautiful = require("beautiful") +screen[1]._resize {x = 0, width = 640, height = 360} +screen.fake_add(660, 0, 640, 360) +awful.tag({ "one", "two", "three" }, screen[1], awful.layout.suit.tile) +awful.tag({ "one", "two", "three" }, screen[2], awful.layout.suit.tile) + +local function color_focus() + for _, c in ipairs(client.get()) do + c.color = c.active and "#ff777733" or beautiful.bg_normal + end +end + +function awful.spawn(name, properties) + client.gen_fake{class = name, name = name, x = 10, y=10, width = 60, height =50, screen = properties.screen} +end + +module.add_event("Spawn some apps", function() + for s in screen do + for i = 1, 4 do + awful.spawn("c"..((s.index -1)*4 + i), {screen = s}) + end + end + + client.focus = client.get()[3] + client.focus.color = "#ff777733" +end) + +module.display_tags() + +module.add_event('Call `focus.global_bydirection` to the top', function() + --DOC_HIDE_END + + --DOC_NEWLINE + -- It will go up in the same column. + awful.client.focus.global_bydirection("up", client.focus) + + --DOC_HIDE_START + color_focus() +end) + + +--DOC_NEWLINE +module.display_tags() + +module.add_event('Call `focus.global_bydirection` to the right', function() + --DOC_HIDE_END + + --DOC_NEWLINE + -- It will cross to screen[2]. + awful.client.focus.global_bydirection("right", client.focus) + + --DOC_HIDE_START + color_focus() +end) + +--DOC_NEWLINE +module.display_tags() + +module.add_event('Call `focus.global_bydirection` to the left', function() + --DOC_HIDE_END + + --DOC_NEWLINE + -- Moves to the first column. + awful.client.focus.global_bydirection("left", client.focus) + + --DOC_HIDE_START + color_focus() +end) + +module.display_tags() + +module.execute { display_screen = true , display_clients = true , + display_label = false, display_client_name = true } diff --git a/tests/examples/sequences/client/focus_byidx1.lua b/tests/examples/sequences/client/focus_byidx1.lua new file mode 100644 index 000000000..f6fcb3cfe --- /dev/null +++ b/tests/examples/sequences/client/focus_byidx1.lua @@ -0,0 +1,81 @@ + --DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_START --DOC_GEN_OUTPUT +local module = ... +local awful = {tag = require("awful.tag"), layout = require("awful.layout"), + client = require("awful.client"), screen = require("awful.screen")} +require("awful.ewmh") +local beautiful = require("beautiful") +screen[1]._resize {x = 0, width = 640, height = 360} +awful.tag({ "one", "two", "three" }, screen[1], awful.layout.suit.tile) + +local function color_focus() + for _, c in ipairs(client.get()) do + c.color = c.active and "#ff777733" or beautiful.bg_normal + end +end + +function awful.spawn(name) + client.gen_fake{class = name, name = name, x = 10, y=10, width = 60, height =50} +end + +--DOC_HIDE_END + -- Print at which index each client is now at. + local function print_indices() + color_focus() + local output = "" + --DOC_NEWLINE + for idx, c in ipairs(client.get()) do + output = output .. c.name .. ":" .. idx .. ", " + end + + --DOC_NEWLINE + print(output) + end + --DOC_NEWLINE +--DOC_HIDE_START + +module.add_event("Spawn some apps", function() + for i = 1, 4 do + awful.spawn("c"..i) + end + + client.focus = client.get()[1] + color_focus() +end) + +module.display_tags() + +module.add_event('Call `focus.byidx`', function() + --DOC_HIDE_END + + print_indices() + + --DOC_NEWLINE + print("Call focus.byidx") + awful.client.focus.byidx(3, client.get()[1]) + + print_indices() + + --DOC_HIDE_START +end) + + +--DOC_NEWLINE +module.display_tags() + +module.add_event('Call `focus.byidx` again', function() + --DOC_HIDE_END + + --DOC_NEWLINE + print("Call focus.byidx") + awful.client.focus.byidx(2, client.get()[4]) + + print_indices() + + --DOC_HIDE_START +end) + + +module.display_tags() + +module.execute { display_screen = true , display_clients = true , + display_label = false, display_client_name = true } diff --git a/tests/examples/sequences/client/focus_byidx1.output.txt b/tests/examples/sequences/client/focus_byidx1.output.txt new file mode 100644 index 000000000..abf64e2e2 --- /dev/null +++ b/tests/examples/sequences/client/focus_byidx1.output.txt @@ -0,0 +1,5 @@ +c1:1, c2:2, c3:3, c4:4, +Call focus.byidx +c1:1, c2:2, c3:3, c4:4, +Call focus.byidx +c1:1, c2:2, c3:3, c4:4, diff --git a/tests/examples/sequences/client/jump_to_urgent1.lua b/tests/examples/sequences/client/jump_to_urgent1.lua new file mode 100644 index 000000000..e3b904738 --- /dev/null +++ b/tests/examples/sequences/client/jump_to_urgent1.lua @@ -0,0 +1,42 @@ + --DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_START +local module = ... +local awful = {tag = require("awful.tag"), layout = require("awful.layout"), + client = require("awful.client")} +local beautiful = require("beautiful") +require("awful.ewmh") +screen[1]._resize {x = 0, width = 160, height = 90} +awful.tag({ "one", "two", "three" }, screen[1], awful.layout.suit.tile) +beautiful.bg_urgent = "#ff0000" + +function awful.spawn(name, properties) + client.gen_fake{class = name, name = name, x = 10, y=10, width = 60, height =50, tags = properties.tags} +end + +module.add_event("Spawn some apps (urgent on tag #2)", function() + for tag_idx = 1, 3 do + for _ = 1, 3 do + awful.spawn("", {tags = {screen[1].tags[tag_idx]}}) + end + end + + client.get()[1].color = "#ff777733" + screen[1].tags[2]:clients()[2].urgent = true + +end) + +--DOC_NEWLINE +module.display_tags() + +module.add_event("Call `awful.client.urgent.jumpto()`", function() + --DOC_HIDE_END + awful.client.urgent.jumpto(false) + --DOC_HIDE_START + + client.get()[1].color = beautiful.bg_normal + screen[1].tags[2]:clients()[2].color = "#ff777733" +end) + +module.display_tags() + +module.execute { display_screen = false, display_clients = true , + display_label = false, display_client_name = true } diff --git a/tests/examples/sequences/client/restore1.lua b/tests/examples/sequences/client/restore1.lua new file mode 100644 index 000000000..37ffc6efe --- /dev/null +++ b/tests/examples/sequences/client/restore1.lua @@ -0,0 +1,67 @@ + --DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_START +local module = ... +local awful = {tag = require("awful.tag"), layout = require("awful.layout"), + client = require("awful.client")} +require("awful.ewmh") +screen[1]._resize {x = 0, width = 640, height = 360} --DOC_HIDE + +awful.tag({ "one", "two", "three" }, screen[1], awful.layout.suit.tile) + +function awful.spawn(name) + client.gen_fake{class = name, name = name, x = 10, y=10, width = 60, height =50} +end + +module.add_event("Spawn some apps", function() + --DOC_HIDE_END + for i = 1, 5 do + awful.spawn("c"..i) + end + --DOC_HIDE_START +end) + +module.display_tags() + +module.add_event("Minimize everything", function() + --DOC_NEWLINE + --DOC_HIDE_END + -- Minimize everything. + for _, c in ipairs(client.get()) do + c.minimized = true + end + --DOC_HIDE_START +end) + +module.display_tags() + +module.add_event("Restore a client", function() + local real_pairs = pairs + + -- Mock for reproducible builds + rawset(screen[1], "selected_tags", screen[1].selected_tags) + + local ret = client.get()[1] + pairs = function(t, ...) --luacheck: globals pairs + local ret2 = ret + ret = nil + + -- Unmock. + if not ret2 then + pairs = real_pairs --luacheck: globals pairs + return pairs(t, ...) + end + + return function() ret2, ret = ret, nil; return ret2 and 1 or nil, ret2 end, t + end + + --DOC_NEWLINE + --DOC_HIDE_END + --DOC_NEWLINE + -- Restore a random client. + awful.client.restore() + --DOC_HIDE_START +end) + +module.display_tags() + +module.execute { display_screen = true , display_clients = true , + display_label = false, display_client_name = true } diff --git a/tests/examples/sequences/client/swap_bydirection1.lua b/tests/examples/sequences/client/swap_bydirection1.lua new file mode 100644 index 000000000..0a3a5816e --- /dev/null +++ b/tests/examples/sequences/client/swap_bydirection1.lua @@ -0,0 +1,68 @@ + --DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_START +local module = ... +local awful = {tag = require("awful.tag"), layout = require("awful.layout"), + client = require("awful.client"), screen = require("awful.screen")} +require("awful.ewmh") +screen[1]._resize {x = 0, width = 640, height = 360} +screen.fake_add(660, 0, 640, 360) +awful.tag({ "one", "two", "three" }, screen[1], awful.layout.suit.tile) +awful.tag({ "one", "two", "three" }, screen[2], awful.layout.suit.tile) + +function awful.spawn(name, properties) + client.gen_fake{class = name, name = name, x = 10, y=10, width = 60, height =50, screen = properties.screen} +end + +module.add_event("Spawn some apps", function() + for s in screen do + for i = 1, 4 do + awful.spawn("c"..((s.index -1)*4 + i), {screen = s}) + end + end + + client.focus = client.get()[3] + client.focus.color = "#ff777733" +end) + +module.display_tags() + +module.add_event('Call `swap.bydirection` to the top', function() + --DOC_HIDE_END + + --DOC_NEWLINE + -- It will go up in the same column. + awful.client.swap.bydirection("up", client.focus) + + --DOC_HIDE_START +end) + + +--DOC_NEWLINE +module.display_tags() + +module.add_event('Call `swap.bydirection` to the right', function() + --DOC_HIDE_END + + --DOC_NEWLINE + -- Nothing happens because it cannot change screen. + awful.client.swap.bydirection("right", client.focus) + + --DOC_HIDE_START +end) + +--DOC_NEWLINE +module.display_tags() + +module.add_event('Call `swap.bydirection` to the left', function() + --DOC_HIDE_END + + --DOC_NEWLINE + -- Moves to the first column. + awful.client.swap.bydirection("left", client.focus) + + --DOC_HIDE_START +end) + +module.display_tags() + +module.execute { display_screen = true , display_clients = true , + display_label = false, display_client_name = true } diff --git a/tests/examples/sequences/client/swap_bydirection2.lua b/tests/examples/sequences/client/swap_bydirection2.lua new file mode 100644 index 000000000..b223599f2 --- /dev/null +++ b/tests/examples/sequences/client/swap_bydirection2.lua @@ -0,0 +1,68 @@ + --DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_START +local module = ... +local awful = {tag = require("awful.tag"), layout = require("awful.layout"), + client = require("awful.client"), screen = require("awful.screen")} +require("awful.ewmh") +screen[1]._resize {x = 0, width = 640, height = 360} +screen.fake_add(660, 0, 640, 360) +awful.tag({ "one", "two", "three" }, screen[1], awful.layout.suit.tile) +awful.tag({ "one", "two", "three" }, screen[2], awful.layout.suit.tile) + +function awful.spawn(name, properties) + client.gen_fake{class = name, name = name, x = 10, y=10, width = 60, height =50, screen = properties.screen} +end + +module.add_event("Spawn some apps", function() + for s in screen do + for i = 1, 4 do + awful.spawn("c"..((s.index -1)*4 + i), {screen = s}) + end + end + + client.focus = client.get()[3] + client.focus.color = "#ff777733" +end) + +module.display_tags() + +module.add_event('Call `swap.global_bydirection` to the top', function() + --DOC_HIDE_END + + --DOC_NEWLINE + -- It will go up in the same column. + awful.client.swap.global_bydirection("up", client.focus) + + --DOC_HIDE_START +end) + + +--DOC_NEWLINE +module.display_tags() + +module.add_event('Call `swap.global_bydirection` to the right', function() + --DOC_HIDE_END + + --DOC_NEWLINE + -- It will cross to screen[2]. + awful.client.swap.global_bydirection("right", client.focus) + + --DOC_HIDE_START +end) + +--DOC_NEWLINE +module.display_tags() + +module.add_event('Call `swap.global_bydirection` to the left', function() + --DOC_HIDE_END + + --DOC_NEWLINE + -- Moves to the first column. + awful.client.swap.global_bydirection("left", client.focus) + + --DOC_HIDE_START +end) + +module.display_tags() + +module.execute { display_screen = true , display_clients = true , + display_label = false, display_client_name = true } diff --git a/tests/examples/sequences/client/swap_byidx1.lua b/tests/examples/sequences/client/swap_byidx1.lua new file mode 100644 index 000000000..f1066735a --- /dev/null +++ b/tests/examples/sequences/client/swap_byidx1.lua @@ -0,0 +1,70 @@ + --DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_START --DOC_GEN_OUTPUT +local module = ... +local awful = {tag = require("awful.tag"), layout = require("awful.layout"), + client = require("awful.client"), screen = require("awful.screen")} +require("awful.ewmh") +screen[1]._resize {x = 0, width = 640, height = 360} +awful.tag({ "one", "two", "three" }, screen[1], awful.layout.suit.tile) + +function awful.spawn(name) + client.gen_fake{class = name, name = name, x = 10, y=10, width = 60, height =50} +end + +--DOC_HIDE_END + -- Print at which index each client is now at. + local function print_indices() + local output = "" + --DOC_NEWLINE + for idx, c in ipairs(client.get()) do + output = output .. c.name .. ":" .. idx .. ", " + end + + --DOC_NEWLINE + print(output) + end + --DOC_NEWLINE +--DOC_HIDE_START + +module.add_event("Spawn some apps", function() + for i = 1, 4 do + awful.spawn("c"..i) + end +end) + +module.display_tags() + +module.add_event('Call `swap.byidx`', function() + --DOC_HIDE_END + + print_indices() + + --DOC_NEWLINE + print("Call swap.byidx") + awful.client.swap.byidx(3, client.get()[1]) + + print_indices() + + --DOC_HIDE_START +end) + + +--DOC_NEWLINE +module.display_tags() + +module.add_event('Call `swap.byidx` again', function() + --DOC_HIDE_END + + --DOC_NEWLINE + print("Call swap.byidx") + awful.client.swap.byidx(2, client.get()[4]) + + print_indices() + + --DOC_HIDE_START +end) + + +module.display_tags() + +module.execute { display_screen = true , display_clients = true , + display_label = false, display_client_name = true } diff --git a/tests/examples/sequences/client/swap_byidx1.output.txt b/tests/examples/sequences/client/swap_byidx1.output.txt new file mode 100644 index 000000000..3747dccc2 --- /dev/null +++ b/tests/examples/sequences/client/swap_byidx1.output.txt @@ -0,0 +1,5 @@ +c1:1, c2:2, c3:3, c4:4, +Call swap.byidx +c4:1, c2:2, c3:3, c1:4, +Call swap.byidx +c4:1, c1:2, c3:3, c2:4, diff --git a/tests/examples/sequences/template.lua b/tests/examples/sequences/template.lua index 4dbf16ab6..760efb70a 100644 --- a/tests/examples/sequences/template.lua +++ b/tests/examples/sequences/template.lua @@ -312,6 +312,11 @@ local function fake_arrange(tag) for _, geo_src in ipairs {param.geometries, flt } do for c, geo in pairs(geo_src) do geo.c = geo.c or c + + if type(c) == "table" and c.geometry then + c:geometry(geo) + end + geo.color = geo.c.color table.insert(ret, geo) end