From 3fe5798a97bd22d29d6d3dfa73098f36a5363754 Mon Sep 17 00:00:00 2001
From: Emmanuel Lepage Vallee <elv1313@gmail.com>
Date: Sat, 18 Aug 2018 16:26:59 -0400
Subject: [PATCH 1/2] ldoc: Add a @sourcefunction section.

It will be used by features introduced in the next commit.
---
 docs/config.ld | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/config.ld b/docs/config.ld
index 0506511ba..a640e4f7c 100644
--- a/docs/config.ld
+++ b/docs/config.ld
@@ -64,6 +64,8 @@ new_type("deprecated", "Deprecated functions", false, "param")
 new_type("legacylayout", "Layout related functions", false, "param")
 -- Have a category for the client layouts
 new_type("clientlayout", "Client layouts", false, "param")
+-- Source functions for the taglist/tasklist/layoutlist
+new_type("sourcefunction", "List source functions", false)
 -- Document some callback prototypes
 new_type("callback", "Callback functions prototype", false, "Parameters")
 -- awful.rules sources

From 96bbbc82f33470b52be1a2500998b836bb574a5b Mon Sep 17 00:00:00 2001
From: Emmanuel Lepage Vallee <elv1313@gmail.com>
Date: Sat, 18 Aug 2018 16:30:15 -0400
Subject: [PATCH 2/2] widget.common: Add custom sources for the taglist and
 tasklist.

The current taglist/tasklist allow filter function to remove elements
from the list. However they don't allow sorting or additional entries
to be listed.

This commit introduced such a concept. It will later be used by the
layoutlist where it becomes more relevant since layouts are used created
"objects".
---
 lib/awful/widget/taglist.lua  | 20 ++++++++++++++++++--
 lib/awful/widget/tasklist.lua | 19 +++++++++++++++++--
 2 files changed, 35 insertions(+), 4 deletions(-)

diff --git a/lib/awful/widget/taglist.lua b/lib/awful/widget/taglist.lua
index a7130769f..d806ada11 100644
--- a/lib/awful/widget/taglist.lua
+++ b/lib/awful/widget/taglist.lua
@@ -61,7 +61,7 @@ local function get_screen(s)
 end
 
 local taglist = { mt = {} }
-taglist.filter = {}
+taglist.filter, taglist.source = {}, {}
 
 --- The tag list main foreground (text) color.
 -- @beautiful beautiful.taglist_fg_focus
@@ -386,7 +386,11 @@ end
 
 local function taglist_update(s, w, buttons, filter, data, style, update_function, args)
     local tags = {}
-    for _, t in ipairs(s.tags) do
+
+    local source = args and args.source or taglist.source.for_screen or nil
+    local list   = source and source(s, args) or s.tags
+
+    for _, t in ipairs(list) do
         if not tag.getproperty(t, "hide") and filter(t) then
             table.insert(tags, t)
         end
@@ -411,6 +415,8 @@ end
 --   update. See `awful.widget.common`.
 -- @tparam[opt] widget args.layout Optional layout widget for tag widgets. Default
 --   is wibox.layout.fixed.horizontal().
+-- @tparam[opt=awful.taglist.source.for_screen] function args.source The
+--  function used to generate the list of tag.
 -- @tparam[opt] table args.widget_template A custom widget to be used for each tag
 -- @tparam[opt={}] table args.style The style overrides default theme.
 -- @tparam[opt=nil] string|pattern args.style.fg_focus
@@ -570,6 +576,16 @@ function taglist.filter.all()
     return true
 end
 
+--- All tags for the defined screen ordered by indices.
+--
+-- This is the default source.
+--
+-- @sourcefunction awful.taglist.source.for_screen
+-- @see screen
+function taglist.source.for_screen(s)
+    return s.tags
+end
+
 function taglist.mt:__call(...)
     return taglist.new(...)
 end
diff --git a/lib/awful/widget/tasklist.lua b/lib/awful/widget/tasklist.lua
index 9bdc50423..332927b59 100644
--- a/lib/awful/widget/tasklist.lua
+++ b/lib/awful/widget/tasklist.lua
@@ -245,7 +245,7 @@ local instances
 -- @see gears.color
 
 -- Public structures
-tasklist.filter = {}
+tasklist.filter, tasklist.source = {}, {}
 
 local function tasklist_label(c, args, tb)
     if not args then args = {} end
@@ -401,7 +401,11 @@ end
 
 local function tasklist_update(s, w, buttons, filter, data, style, update_function, args)
     local clients = {}
-    for _, c in ipairs(capi.client.get()) do
+
+    local source = args and args.source or tasklist.source.all_clients or nil
+    local list   = source and source(s, args) or capi.client.get()
+
+    for _, c in ipairs(list) do
         if not (c.skip_taskbar or c.hidden
             or c.type == "splash" or c.type == "dock" or c.type == "desktop")
             and filter(c, s) then
@@ -430,6 +434,8 @@ end
 --   update. See `awful.widget.common.list_update`.
 -- @tparam[opt] table args.layout Container widget for tag widgets. Default
 --   is `wibox.layout.flex.horizontal`.
+-- @tparam[opt=awful.tasklist.source.all_clients] function args.source The
+--  function used to generate the list of client.
 -- @tparam[opt] table args.widget_template A custom widget to be used for each client
 -- @tparam[opt={}] table args.style The style overrides default theme.
 -- @tparam[opt=nil] string|pattern args.style.fg_normal
@@ -677,6 +683,15 @@ function tasklist.filter.focused(c, screen)
     return get_screen(c.screen) == get_screen(screen) and capi.client.focus == c
 end
 
+--- Get all the clients in an undefined order.
+--
+-- This is the default source.
+--
+-- @sourcefunction awful.tasklist.source.all_clients
+function tasklist.source.all_clients()
+    return capi.client.get()
+end
+
 function tasklist.mt:__call(...)
     return tasklist.new(...)
 end