Aire-One
/
awesome
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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

This commit is contained in:
Emmanuel Lepage Vallee 2021-10-18 14:33:14 -07:00
parent cbec148540
commit b2603f6a86
15 changed files with 653 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
lib/awful/client.lua
View File

@ -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.

6
lib/awful/client/focus.lua
View File

@ -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)

62
tests/examples/sequences/client/cycle1.lua Normal file
View File

@ -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 }

0
tests/examples/sequences/client/cycle1.output.txt Normal file
View File

78
tests/examples/sequences/client/focus_bydirection1.lua Normal file
View File

@ -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 }

78
tests/examples/sequences/client/focus_bydirection2.lua Normal file
View File

@ -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 }

81
tests/examples/sequences/client/focus_byidx1.lua Normal file
View File

@ -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 }

5
tests/examples/sequences/client/focus_byidx1.output.txt Normal file
View File

@ -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,

42
tests/examples/sequences/client/jump_to_urgent1.lua Normal file
View File

@ -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 }

67
tests/examples/sequences/client/restore1.lua Normal file
View File

@ -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 }

68
tests/examples/sequences/client/swap_bydirection1.lua Normal file
View File

@ -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 }

68
tests/examples/sequences/client/swap_bydirection2.lua Normal file
View File

@ -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 }

70
tests/examples/sequences/client/swap_byidx1.lua Normal file
View File

@ -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 }

5
tests/examples/sequences/client/swap_byidx1.output.txt Normal file
View File

@ -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,

5
tests/examples/sequences/template.lua
View File

@ -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