From 8fb4e2b721492d396d6659152cd0e6107a69b385 Mon Sep 17 00:00:00 2001
From: Emmanuel Lepage Vallee <elv1313@gmail.com>
Date: Sat, 5 Sep 2020 17:55:34 -0700
Subject: [PATCH] doc: Add a client "sticky" example.

---
 objects/client.c                           | 23 ++++++++++++++++
 tests/examples/sequences/client/sticky.lua | 31 ++++++++++++++++++++++
 tests/examples/sequences/template.lua      | 23 +++++++++++++---
 3 files changed, 74 insertions(+), 3 deletions(-)
 create mode 100644 tests/examples/sequences/client/sticky.lua

diff --git a/objects/client.c b/objects/client.c
index 581288ed..f684ee7b 100644
--- a/objects/client.c
+++ b/objects/client.c
@@ -815,6 +815,12 @@ lua_class_t client_class;
  * @propemits false false
  * @request client geometry fullscreen granted When the client must be resized
  *  because it became (or stop being) fullscreen.
+ * @see maximized_horizontal
+ * @see maximized_vertical
+ * @see immobilized_horizontal
+ * @see immobilized_vertical
+ * @see maximized
+
  */
 
 /**
@@ -828,6 +834,11 @@ lua_class_t client_class;
  * @request client geometry maximized granted When the client must be resized
  *  because it became (or stop being) maximized.
  * @see request::border
+ * @see maximized_horizontal
+ * @see maximized_vertical
+ * @see fullscreen
+ * @see immobilized_horizontal
+ * @see immobilized_vertical
  */
 
 /**
@@ -840,6 +851,11 @@ lua_class_t client_class;
  * @propemits false false
  * @request client geometry maximized_horizontal granted When the client must be resized
  *  because it became (or stop being) maximized horizontally.
+ * @see maximized_vertical
+ * @see fullscreen
+ * @see immobilized_horizontal
+ * @see immobilized_vertical
+ * @see maximized
  */
 
 /**
@@ -852,6 +868,11 @@ lua_class_t client_class;
  * @propemits false false
  * @request client geometry maximized_vertical granted When the client must be resized
  *  because it became (or stop being) maximized vertically.
+ * @see maximized_horizontal
+ * @see fullscreen
+ * @see immobilized_horizontal
+ * @see immobilized_vertical
+ * @see maximized
  */
 
 /**
@@ -994,6 +1015,8 @@ lua_class_t client_class;
  * per screens rather than globally like some other
  * implementations.
  *
+ * @DOC_sequences_client_sticky_EXAMPLE@
+ *
  * @property sticky
  * @tparam boolean sticky
  * @propemits false false
diff --git a/tests/examples/sequences/client/sticky.lua b/tests/examples/sequences/client/sticky.lua
new file mode 100644
index 00000000..163365a7
--- /dev/null
+++ b/tests/examples/sequences/client/sticky.lua
@@ -0,0 +1,31 @@
+--DOC_GEN_IMAGE --DOC --DOC_NO_USAGE --DOC_ASTERISK
+local module = ... --DOC_HIDE
+local awful = {tag = require("awful.tag"), layout = require("awful.layout") } --DOC_HIDE
+screen[1]._resize {x = 0, width = 128, height = 96} --DOC_HIDE
+
+
+function awful.spawn(_, args) --DOC_HIDE
+    local c = client.gen_fake{x = 10, y = 10, height=50, width=50} --DOC_HIDE
+    c:tags{screen[1].tags[1]} --DOC_HIDE
+end --DOC_HIDE
+
+awful.tag({ "one", "two", "three", "four", "five" }, screen[1]) --DOC_HIDE
+
+module.add_event("Add a client", function() --DOC_HIDE
+    -- Add a client.
+    awful.spawn("xterm")
+    assert(#screen[1].clients == 1) --DOC_HIDE
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+--DOC_NEWLINE
+
+module.add_event("Set sticky = true", function() --DOC_HIDE
+    -- Set sticky = true
+    screen[1].clients[1].sticky = true
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+module.execute {show_empty = true} --DOC_HIDE
diff --git a/tests/examples/sequences/template.lua b/tests/examples/sequences/template.lua
index 7f4e788d..73d60504 100644
--- a/tests/examples/sequences/template.lua
+++ b/tests/examples/sequences/template.lua
@@ -242,11 +242,28 @@ local function gen_cls(c,results)
     return ret
 end
 
+local function get_all_tag_clients(t)
+    local s = t.screen
+
+    local clients = gtable.clone(t:clients(), false)
+
+    for _, c in ipairs(s.clients) do
+        if c.sticky then
+            if not gtable.hasitem(clients, c) then
+                table.insert(clients, c)
+            end
+        end
+    end
+
+    return clients
+end
+
 local function fake_arrange(tag)
     local cls,results,flt = {},setmetatable({},{__mode="k"}),{}
-    local _, l = tag.screen, tag.layout
+    local l = tag.layout
     local focus, focus_wrap = capi.client.focus, nil
-    for _ ,c in ipairs (tag:clients()) do
+
+    for _ ,c in ipairs (get_all_tag_clients(tag)) do
         -- Handle floating client separately
         if not c.minimized then
             local floating = c.floating
@@ -758,7 +775,7 @@ function module.display_tags()
                     master_width_factor = t.master_width_factor,
                     client_geo          = fake_arrange(t),
                 })
-                assert(#st[#st].client_geo == #t:clients())
+                assert(#st[#st].client_geo == #get_all_tag_clients(t))
             end
             table.insert(ret, {tags=st})
         end