[RFC] support for awesome v4 and other fixes/enhancements

.luacheckrc

@@ -0,0 +1,44 @@
+-- Only allow symbols available in all Lua versions
+std = "min"
+
+-- Get rid of "unused argument self"-warnings
+self = false
+
+-- The default config may set global variables
+-- files["init.lua"].allow_defined_top = true
+
+-- This file itself
+files[".luacheckrc"].ignore = {"111", "112", "131"}
+
+-- Global objects defined by the C code
+read_globals = {
+    "awesome",
+    "button",
+    "client",
+    "dbus",
+    "drawable",
+    "drawin",
+    "key",
+    "keygrabber",
+    "mousegrabber",
+    "root",
+    "selection",
+    "tag",
+    "window",
+    -- Global settings.
+    "modkey",
+}
+
+-- screen may not be read-only, because newer luacheck versions complain about
+-- screen[1].tags[1].selected = true.
+-- The same happens with the following code:
+--   local tags = mouse.screen.tags
+--   tags[7].index = 4
+-- client may not be read-only due to client.focus.
+globals = {
+    "screen",
+    "mouse",
+    "client"
+}
+
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

.travis.yml

@@ -0,0 +1,20 @@
+# Based on https://github.com/mpeterv/hererocks
+
+language: python
+sudo: false
+
+env:
+  - LUA="lua 5.3"
+
+install:
+  - pip install hererocks
+  - hererocks env --$LUA -rlatest
+  - source env/bin/activate
+  - luarocks install luacheck
+
+script:
+  - luacheck *.lua
+
+branches:
+  only:
+  - master

README.md

@@ -82,22 +82,20 @@ Setup `modkey+Tab` to cycle through all windows (assuming modkey is
 
 ```lua
 -- modkey+Tab: cycle through all clients.
-awful.key({ modkey,         }, "Tab", function(c)
-        cyclefocus.cycle(1, {modifier="Super_L"})
+awful.key({ modkey }, "Tab", function(c)
+        cyclefocus.cycle({modifier="Super_L"})
 end),
 -- modkey+Shift+Tab: backwards
 awful.key({ modkey, "Shift" }, "Tab", function(c)
-        cyclefocus.cycle(-1, {modifier="Super_L"})
+        cyclefocus.cycle({modifier="Super_L"})
 end),
 ```
 
-The first argument to `cyclefocus.cycle` is the starting direction: 1 means
-backwards in history (incrementing index for the history stack), -1 means to go
-in the opposite direction. `1` is the normal behavior, while `-1` refers to the
-shifted version.
-
-The second argument is a table of optional arguments. We need to pass the
-modifier being used (as seen by awesome's `keygrabber`) here.
+You can pass a table of optional arguments.
+We need to pass the modifier (as seen by awesome's `keygrabber`) here.
+Internally the direction gets set according to if the `Shift` modifier key
+is present, so that the second definition is only necessary to trigger it in
+the opposite direction from the beginning.
 
 See the `init.lua` file for a full reference, or refer to the [settings section
 below](#settings).
@@ -110,7 +108,7 @@ There is a helper function `cyclefocus.key`, which can be used instead of
 ```lua
 -- Alt-Tab: cycle through clients on the same screen.
 -- This must be a clientkeys mapping to have source_c available in the callback.
-cyclefocus.key({ "Mod1", }, "Tab", 1, {
+cyclefocus.key({ "Mod1", }, "Tab", {
     -- cycle_filters as a function callback:
     -- cycle_filters = { function (c, source_c) return c.screen == source_c.screen end },
 
@@ -120,10 +118,11 @@ cyclefocus.key({ "Mod1", }, "Tab", 1, {
 }),
 ```
 
-The first two arguments are the same as with `awful.key`: a list of modifiers and
-the key. Then follows the direction and the list of optional arguments again.
-(here the `modifier` argument is not required, because it is given in the first
-argument).
+The first two arguments are the same as with `awful.key`: a list of modifiers
+and the key. Then the table with optional arguments to `cyclefocus.cycle()`
+follows.
+(here the `modifier` argument is not required, because it gets used from
+the first argument).
 
 #### `cycle_filters`
 
@@ -215,36 +214,35 @@ The default settings are:
 
 ```lua
 cyclefocus = {
-    -- Should clients be raised during cycling?
-    raise_clients = true,
-    -- Should clients be focused during cycling?
+    -- Should clients get shown during cycling?
+    -- This should be a function (or `false` to disable showing clients), which
+    -- receives a client object, and can make use of cyclefocus.show_client
+    -- (the default implementation).
+    show_clients = true,
+    -- Should clients get focused during cycling?
+    -- This is required for the tasklist to highlight the selected entry.
     focus_clients = true,
 
     -- How many entries should get displayed before and after the current one?
-    display_next_count = 2,
-    display_prev_count = 2,  -- only 0 for prev, works better with naughty notifications.
-
-    -- Preset to be used for the notification.
-    naughty_preset = {
-        position = 'top_left',
-        timeout = 0,
-    },
-
-    naughty_preset_for_offset = {
-        -- Default callback, which will be applied for all offsets (first).
+    display_next_count = 3,
+    display_prev_count = 3,
+
+    -- Default preset to for entries.
+    -- `preset_for_offset` (below) gets added to it.
+    default_preset = {},
+
+    --- Templates for entries in the list.
+    -- The following arguments get passed to a callback:
+    --  - client: the current client object.
+    --  - idx: index number of current entry in clients list.
+    --  - displayed_list: the list of entries in the list, possibly filtered.
+    preset_for_offset = {
+        -- Default callback, which will gets applied for all offsets (first).
         default = function (preset, args)
             -- Default font and icon size (gets overwritten for current/0 index).
             preset.font = 'sans 8'
             preset.icon_size = 36
-            preset.text = escape_markup(cyclefocus.get_object_name(args.client))
-
-            -- Display the notification on the current screen (mouse).
-            preset.screen = capi.mouse.screen
-
-            -- Set notification width, based on screen/workarea width.
-            local s = preset.screen
-            local wa = capi.screen[s].workarea
-            preset.width = floor(wa.width * 0.618)
+            preset.text = escape_markup(cyclefocus.get_client_title(args.client, false))
 
             preset.icon = cyclefocus.icon_loader(args.client.icon)
         end,
@@ -253,31 +251,42 @@ cyclefocus = {
         ["0"] = function (preset, args)
             preset.font = 'sans 12'
             preset.icon_size = 48
-            -- Use get_object_name to handle .name=nil.
-            preset.text = escape_markup(cyclefocus.get_object_name(args.client))
-            -- Add screen number if there are multiple.
+            preset.text = escape_markup(cyclefocus.get_client_title(args.client, true))
+            -- Add screen number if there is more than one.
             if screen.count() > 1 then
-                preset.text = preset.text .. " [screen " .. args.client.screen .. "]"
+                preset.text = preset.text .. " [screen " .. tostring(args.client.screen.index) .. "]"
             end
             preset.text = preset.text .. " [#" .. args.idx .. "] "
             preset.text = '<b>' .. preset.text .. '</b>'
         end,
 
         -- You can refer to entries by their offset.
-        ["-1"] = function (preset, args)
-            -- preset.icon_size = 32
-        end,
-        ["1"] = function (preset, args)
-            -- preset.icon_size = 32
-        end
+        -- ["-1"] = function (preset, args)
+        --     -- preset.icon_size = 32
+        -- end,
+        -- ["1"] = function (preset, args)
+        --     -- preset.icon_size = 32
+        -- end
     },
 
     -- Default builtin filters.
-    -- These are meant to get applied always, but you could override them.
+    -- (meant to get applied always, but you could override them)
     cycle_filters = {
-        function(c, source_c) return not c.minimized end,
+        function(c, source_c) return not c.minimized end,  --luacheck: no unused args
     },
 
+    -- EXPERIMENTAL: only add clients to the history that have been focused by
+    -- cyclefocus.
+    -- This allows to switch clients using other methods, but those are then
+    -- not added to cyclefocus' internal history.
+    -- The get_next_client function will then first consider the most recent
+    -- entry in the history stack, if it's not focused currently.
+    --
+    -- You can use cyclefocus.history.add to manually add an entry, or
+    -- cyclefocus.history.append if you want to add it to the end of the stack.
+    -- This might be useful in a request::activate signal handler.
+    -- only_add_internal_focus_changes_to_history = true,
+
     -- The filter to ignore clients altogether (get not added to the history stack).
     -- This is different from the cycle_filters.
     -- The function should return true / the client if it's ok, nil otherwise.
@@ -338,6 +347,8 @@ You can report bugs and wishes at the [Github issue tracker][].
 
 Pull requests would be awesome! :)
 
+## Donate
+
 [![Flattr this git repo](http://api.flattr.com/button/flattr-badge-large.png)](https://flattr.com/submit/auto?user_id=blueyed&url=https://github.com/blueyed/awesome-cyclefocus&title=awesome-cyclefocus&language=en&tags=github&category=software)
 
 Bitcoin: 16EVhEpXxfNiT93qT2uxo4DsZSHzNdysSp