doc: Add an awful.tag.clear example.

lib/awful/tag.lua

@@ -354,6 +354,9 @@ end
 -- @see clear
 
 --- Remove all tagged clients.
+--
+-- @DOC_sequences_tag_clear_EXAMPLE@
+--
 -- @method clear
 -- @tparam table args The arguments.
 -- @tparam tag args.fallback_tag A fallback tag.

tests/examples/sequences/tag/clear.lua

@@ -0,0 +1,50 @@
+ --DOC_GEN_IMAGE --DOC --DOC_NO_USAGE
+local module = ... --DOC_HIDE
+local awful = {tag = require("awful.tag"), --DOC_HIDE
+    layout = require("awful.layout"), --DOC_HIDE
+} --DOC_HIDE
+screen[1]._resize {x = 0, width = 128, height = 96} --DOC_HIDE
+
+function awful.spawn(_, args) --DOC_HIDE
+    local c = client.gen_fake{} --DOC_HIDE
+    c:tags({args.tag}) --DOC_HIDE
+    assert(#c:tags() == 1) --DOC_HIDE
+    assert(c:tags()[1] == args.tag) --DOC_HIDE
+end --DOC_HIDE
+
+assert(awful.layout.layouts[1]) --DOC_HIDE
+local some_layouts = {--DOC_HIDE
+    awful.layout.suit.fair,--DOC_HIDE
+    awful.layout.suit.fair,--DOC_HIDE
+} --DOC_HIDE
+
+    -- Calling awful.tag.new
+    awful.tag({ "one", "two" }, screen[1], some_layouts)
+
+assert(#screen[1].tags == 2) --DOC_HIDE
+for k, t in ipairs(screen[1].tags) do --DOC_HIDE
+    assert(t.layout and t.layout == some_layouts[k]) --DOC_HIDE
+    assert(#t:clients() == 0) --DOC_HIDE
+end --DOC_HIDE
+
+--DOC_NEWLINE
+
+module.add_event("Calling awful.tag.new and add some clients", function() --DOC_HIDE
+    for _, t in ipairs(screen[1].tags) do--DOC_HIDE
+        for _ = 1, 3 do --DOC_HIDE
+            awful.spawn("xterm", {tag = t})--DOC_HIDE
+        end --DOC_HIDE
+        assert(#t:clients() == 3) --DOC_HIDE
+    end --DOC_HIDE
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+module.add_event("Call `:clear()` on the first tag.", function() --DOC_HIDE
+    -- Call :clear() on the first tag.
+    screen[1].tags[1]:clear{}
+end)
+
+module.display_tags() --DOC_HIDE
+
+module.execute {show_empty = true} --DOC_HIDE

tests/examples/shims/client.lua

@@ -170,6 +170,7 @@ function client.gen_fake(args)
 
         for _, t in ipairs(old_tags) do
             ret:emit_signal("untagged", t)
+            t:emit_signal("untagged", ret)
             t:emit_signal("property::tags")
         end
 

tests/examples/shims/tag.lua

@@ -1,4 +1,5 @@
 local gears_obj = require("gears.object")
+local gtable = require("gears.table")
 
 local tag, meta = awesome._shim_fake_class()
 
@@ -11,6 +12,22 @@ local function has_selected_tag(s)
     return false
 end
 
+local function get_clients(self)
+    local list = {}
+
+    for _, c in ipairs(client.get()) do
+        if #c:tags() > 0 then
+            for _, t in ipairs(c:tags()) do
+                if t == self then
+                    table.insert(list, c)
+                end
+            end
+        end
+    end
+
+    return list
+end
+
 local function new_tag(_, args)
     local ret = gears_obj()
     awesome._forward_class(ret, tag)
@@ -23,18 +40,40 @@ local function new_tag(_, args)
     -- Deprecated.
     ret.data = ret._private
 
-    function ret:clients(_) --TODO handle new
+    function ret:clients(new_clients)
-        local list = {}
+        local old_clients = get_clients(ret)
-        for _, c in ipairs(client.get()) do
+
-            if #c:tags() > 0 then
+        -- Remove the old clients.
-                for _, t in ipairs(c:tags()) do
+        if new_clients then
-                    if t == ret then
+            for _, c in ipairs(client.get()) do
-                        table.insert(list, c)
+                local had_client = gtable.hasitem(old_clients, c)
+                local has_client = gtable.hasitem(new_clients, c)
+                 if had_client and not has_client then
+                    local ctags = gtable.clone(c:tags(), false)
+
+                    for k, t in ipairs(ctags) do
+                        if t == self then
+                            table.remove(ctags, k)
+                            c:tags(ctags)
+                        end
                     end
                 end
             end
+
+            -- Add the new clients.
+            for _, c in ipairs(new_clients) do
+
+                if new_clients and not gtable.hasitem(old_clients, c) then
+                    local ctags = gtable.clone(c:tags(), false)
+                    table.insert(ctags, self)
+                    c:tags(ctags)
+                end
+            end
         end
 
+        -- Generate the client list.
+        local list = get_clients(ret)
+
         return list
     end