awful.client.focus.history

[Joren Heit]

Hi all,

I'm experiencing weird problems with the focus history while implementing
Alt-Tab in Awesome 3.5.5. While alt-tabbing, the script is cycling through
a table containing the history, constructed like this:

   local idx = 0
   local c = awful.client.focus.history.get(s, idx)

   while c do
      table.insert(altTabTable, c)
      idx = idx + 1
      c = awful.client.focus.history.get(s, idx)
   end

For some reason, the minimized clients are not contained at all in the
history, so afterwards I have to iterate through the list of all clients (
client.get()) to add those to my altTabTable as well.

When the user (me) releases the Alt-key, the currently selected window is
set as focussed and is raised on top of the other ones. However, this
messes up the history. For example, if I have three windows open in the
current tag, say

   1. Iceweasel
   2. Terminal
   3. Chromium

where #1 is focussed, and I Alt-Tab my way to Chromium (raising but not
focussing the terminal on the way there), I would expect the new order to
be like this:

   1. Chromium
   2. Iceweasel
   3. Terminal

Unfortunately, this is not the case. Instead, #2 and #3 have swapped
positions. I have no idea why, but I thought I might be able to get around
this by just clearing the entire history and reinserting clients in the
order I want. Something like this:
   -- delete all clients from history
   for i = 1, #altTabTable do
      awful.client.focus.history.delete(altTabTable[i])
   end

   -- reinsert every client in reverse order
   for i = 0, #altTabTable - 1 do
       if i ~= altTabIndex then -- skip selected window
           awful.client.focus.history.add(altTabTable[#altTabTable - i])
       end
   end

This code assumes that the history is some sort of LIFO container (a stack
basically), where you can add and remove things onto/from the top. However,
it doesn't work. To be honest, it's hard to explain what happens. After
struggling with this for over an hour, I can't find the patience anymore to
figure out what kind of effect this exactly had, or what the logic behind
it was. By now, I have tried so many different solutions, some of which
even crashed Awesome. Things that didn't work:

   1. The above
   2. Deleting and adding (in that order) the selected client. One might
   expect that this would cause the client to move to the top of the stack.
   Nope.
   3. Iterating over the history using get, then deleting
   4. The above, but reinserting in current order

Does anyone have guidelines on how to use this whole history thing? It's
one of the many frustratingly poorly documented features of Awesome... :-(
Honestly, better documentation is what would be really Awesome!

Thanks in advance,
Joren