doc: Add images for awful.client.* functions.

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.

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)

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 }

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 }

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 }

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 }

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, 

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 }

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 }

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 }

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 }

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 }

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, 

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