different tab cycling

7 files changed, 1858 insertions, 7 deletions

diff --git a/config/awesome/cyclefocus/.luacheckrc b/config/awesome/cyclefocus/.luacheckrc
new file mode 100644
index 0000000..8ee3bda
--- /dev/null
+++ b/config/awesome/cyclefocus/.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
diff --git a/config/awesome/cyclefocus/.travis.yml b/config/awesome/cyclefocus/.travis.yml
new file mode 100644
index 0000000..f9e53f7
--- /dev/null
+++ b/config/awesome/cyclefocus/.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
diff --git a/config/awesome/cyclefocus/LICENSE b/config/awesome/cyclefocus/LICENSE
new file mode 100644
index 0000000..d7f1051
--- /dev/null
+++ b/config/awesome/cyclefocus/LICENSE
@@ -0,0 +1,339 @@
+GNU GENERAL PUBLIC LICENSE
+                       Version 2, June 1991
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc., <http://fsf.org/>
+ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users.  This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it.  (Some other Free Software Foundation software is covered by
+the GNU Lesser General Public License instead.)  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+  To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must show them these terms so they know their
+rights.
+
+  We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+  Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+  Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                    GNU GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License.  The "Program", below,
+refers to any such program or work, and a "work based on the Program"
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language.  (Hereinafter, translation is included without limitation in
+the term "modification".)  Each licensee is addressed as "you".
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+  1. You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+  2. You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) You must cause the modified files to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    b) You must cause any work that you distribute or publish, that in
+    whole or in part contains or is derived from the Program or any
+    part thereof, to be licensed as a whole at no charge to all third
+    parties under the terms of this License.
+
+    c) If the modified program normally reads commands interactively
+    when run, you must cause it, when started running for such
+    interactive use in the most ordinary way, to print or display an
+    announcement including an appropriate copyright notice and a
+    notice that there is no warranty (or else, saying that you provide
+    a warranty) and that users may redistribute the program under
+    these conditions, and telling the user how to view a copy of this
+    License.  (Exception: if the Program itself is interactive but
+    does not normally print such an announcement, your work based on
+    the Program is not required to print an announcement.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+    a) Accompany it with the complete corresponding machine-readable
+    source code, which must be distributed under the terms of Sections
+    1 and 2 above on a medium customarily used for software interchange; or,
+
+    b) Accompany it with a written offer, valid for at least three
+    years, to give any third party, for a charge no more than your
+    cost of physically performing source distribution, a complete
+    machine-readable copy of the corresponding source code, to be
+    distributed under the terms of Sections 1 and 2 above on a medium
+    customarily used for software interchange; or,
+
+    c) Accompany it with the information you received as to the offer
+    to distribute corresponding source code.  (This alternative is
+    allowed only for noncommercial distribution and only if you
+    received the program in object code or executable form with such
+    an offer, in accord with Subsection b above.)
+
+The source code for a work means the preferred form of the work for
+making modifications to it.  For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable.  However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  4. You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+  5. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Program or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+  6. Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+  7. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  8. If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded.  In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+  9. The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program
+specifies a version number of this License which applies to it and "any
+later version", you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation.  If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+  10. If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission.  For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this.  Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+                            NO WARRANTY
+
+  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    {description}
+    Copyright (C) {year}  {fullname}
+
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License along
+    with this program; if not, write to the Free Software Foundation, Inc.,
+    51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+    Gnomovision version 69, Copyright (C) year name of author
+    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, the commands you use may
+be called something other than `show w' and `show c'; they could even be
+mouse-clicks or menu items--whatever suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
+  `Gnomovision' (which makes passes at compilers) written by James Hacker.
+
+  {signature of Ty Coon}, 1 April 1989
+  Ty Coon, President of Vice
+
+This General Public License does not permit incorporating your program into
+proprietary programs.  If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.
diff --git a/config/awesome/cyclefocus/README.md b/config/awesome/cyclefocus/README.md
new file mode 100644
index 0000000..221c837
--- /dev/null
+++ b/config/awesome/cyclefocus/README.md
@@ -0,0 +1,347 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](http://doctoc.herokuapp.com/)*
+
+- [awesome-cyclefocus](#awesome-cyclefocus)
+  - [Screenshot](#screenshot)
+  - [Installation](#installation)
+  - [Keybindings](#keybindings)
+    - [Example 1: cycle through all windows](#example-1-cycle-through-all-windows)
+    - [Example 2: cycle through windows on the same screen and tag](#example-2-cycle-through-windows-on-the-same-screen-and-tag)
+      - [`cycle_filters`](#cycle_filters)
+      - [Predefined filters](#predefined-filters)
+    - [Example 3: cycle through clients with the same class](#example-3-cycle-through-clients-with-the-same-class)
+  - [Reference](#reference)
+    - [Configuration](#configuration)
+      - [<a name="settings"></a>Settings](#a-namesettingsasettings)
+  - [Status](#status)
+- [Bugs, Feedback and Support](#bugs-feedback-and-support)
+  - [Donate](#donate)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+# awesome-cyclefocus
+
+awesome-cyclefocus is a module/plugin for the [awesome window
+manager][], which provides methods to cycle through
+the most recently used clients (typically known as Alt-Tab).
+
+It allows to easily filter the list of windows to be cycled through, e.g. by
+screen, tags, window class, name/title etc.
+
+## Screenshot
+
+![Screenshot](screenshot.png)
+
+Please note that the graphical aspect needs to be developed, but since people
+like screenshots…
+
+## Installation
+
+*Requirements:* awesome-cyclefocus requires Awesome 4+.
+
+Create a subdirectory `cyclefocus` in your awesome config directory, e.g.
+
+    cd ~/.config/awesome
+    git clone https://github.com/blueyed/awesome-cyclefocus cyclefocus
+
+Then include it from your config file (`~/.config/awesome/rc.lua`), somewhere
+at the beginning:
+
+```lua
+local cyclefocus = require('cyclefocus')
+```
+
+## Keybindings
+
+Then you can define the keybindings.
+
+While you can use it with the `globalkeys` configuation, you should use
+the `clientkeys` table for any bindings which use `cycle_filters`.
+
+The default for `modkey+Tab` in awesome (3.5.2) is:
+```lua
+awful.key({ modkey,           }, "Tab",
+    function ()
+        awful.client.focus.history.previous()
+        if client.focus then
+            client.focus:raise()
+        end
+    end),
+```
+You should disable it (e.g. by commenting it out), and add your method below.
+
+Here are three methods to setup the key mappings:
+
+### Example 1: cycle through all windows
+
+Setup `modkey+Tab` to cycle through all windows (assuming `modkey` is
+`Mod4`/`Super_L`, which is the default):
+
+```lua
+-- modkey+Tab: cycle through all clients.
+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({modifier="Super_L"})
+end),
+```
+
+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 (or the [settings section below](#settings)) for a full
+reference.
+
+### Example 2: cycle through windows on the same screen and tag
+
+You can use `cyclefocus.key` (a wrapper around `awful.key`) like this:
+
+```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", {
+    -- cycle_filters as a function callback:
+    -- cycle_filters = { function (c, source_c) return c.screen == source_c.screen end },
+
+    -- cycle_filters from the default filters:
+    cycle_filters = { cyclefocus.filters.same_screen, cyclefocus.filters.common_tag },
+    keys = {'Tab', 'ISO_Left_Tab'}  -- default, could be left out
+}),
+```
+
+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).
+
+NOTE: this needs to go into `clientkeys`.
+
+#### `cycle_filters`
+
+In this case the `cycle_filters` argument is used, which is a list of filters
+to apply while cycling through the focus history: it gets passed a `client`
+object, and optionally another `client` object for the source (where the
+cycling started).
+For the source client to be available, it needs to be an entry in the
+`clientkeys` table.
+
+You can pass functions here, or use one of the predefined filters:
+
+#### Predefined filters
+
+The following filters are available by default:
+
+```lua
+-- A set of default filters, which can be used for cyclefocus.cycle_filters.
+cyclefocus.filters = {
+    -- Filter clients on the same screen.
+    same_screen = function (c, source_c) return c.screen == source_c.screen end,
+
+    same_class = function (c, source_c)
+        return c.class == source_c.class
+    end,
+
+    -- Only marked clients (via awful.client.mark and .unmark).
+    marked = function (c, source_c)
+        return awful.client.ismarked(c)
+    end,
+
+    common_tag  = function (c, source_c)
+        for _, t in pairs(c:tags()) do
+            for _, t2 in pairs(source_c:tags()) do
+                if t == t2 then
+                    cyclefocus.debug("Filter: client shares tag '" .. t.name .. " with " .. c.name)
+                    return true
+                end
+            end
+        end
+        return false
+    end
+}
+```
+
+### Example 3: cycle through clients with the same class
+
+The following will cycle through windows, which share the same window class
+(e.g. only Firefox windows, when starting from a Firefox window):
+
+```lua
+-- Alt-^: cycle through clients with the same class name.
+cyclefocus.key({ "Mod1", }, "#49", 1, {
+        cycle_filter = function (c, source_c) return c.class == source_c.class end,
+        keys = { "°", "^" },  -- the keys to be handled, wouldn't be required if the keycode was available in keygrabber.
+}),
+cyclefocus.key({ "Mod1", "Shift", }, "#49", -1, {  -- keycode #49 => ^/° on german keyboard, upper left below Escape and next to 1.
+        cycle_filter = function (c, source_c) return c.class == source_c.class end,
+        keys = { "°", "^" },  -- the keys to be handled, wouldn't be required if the keycode was available in keygrabber.
+}),
+```
+
+The key argument uses the keycode notation (`#49`) and refers (probably) to the key
+below Escape, above Tab and next to the first digit (1).
+It should be the same shortcut, as what Ubuntu's Unity uses to cycle through
+the windows of a single application.
+
+NOTE: You need to pass the keys this refers to via the `keys` argument, so that
+the keygrabber considers those only.
+In the example above, `^` and `°` refers to the key on the German keyboard
+layout (un-shifted and shifted, i.e. with Shift pressed and released).
+
+NOTE: this needs to go into `clientkeys`.
+
+## Reference
+
+### Configuration
+
+awesome-cyclefocus can be configured by passing optional arguments to the
+`cyclefocus.cycle` or `cyclefocus.key` functions, or by setting defaults, after
+loading `cyclefocus`:
+
+#### <a name="settings"></a>Settings
+
+The default settings are:
+
+```lua
+cyclefocus = {
+    -- 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 = 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_client_title(args.client, false))
+
+            preset.icon = cyclefocus.icon_loader(args.client.icon)
+        end,
+
+        -- Preset for current entry.
+        ["0"] = function (preset, args)
+            preset.font = 'sans 12'
+            preset.icon_size = 48
+            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 " .. 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
+    },
+
+    -- Default builtin filters.
+    -- (meant to get applied always, but you could override them)
+    cycle_filters = {
+        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.
+    filter_focus_history = awful.client.focus.filter,
+
+    -- Display notifications while cycling?
+    -- WARNING: without raise_clients this will not make sense probably!
+    display_notifications = true,
+
+    -- Debugging: messages get printed, and should show up in ~/.xsession-errors etc.
+    -- 1: enable, 2: verbose, 3: very verbose, 4: much verbose.
+    debug_level = 0,
+    -- Use naughty notifications for debugging (additional to printing)?
+    debug_use_naughty_notify = 1,
+}
+```
+
+You can change them like this:
+```lua
+cyclefocus = require("cyclefocus")
+cyclefocus.debug_level = 2
+```
+
+You can also use custom settings when calling `cyclefocus.cycle` or
+`cyclefocus.key` via `args`, e.g. to not display notifications when switching
+between clients on the same tag:
+```lua
+cyclefocus.key({ modkey, }, "Tab", 1, {
+    cycle_filters = { cyclefocus.filters.common_tag },
+    display_notifications = false,
+    modifier='Super_L', keys={'Tab', 'ISO_Left_Tab'}
+}),
+cyclefocus.key({ modkey, "Shift", }, "Tab", 1, {
+    cycle_filters = { cyclefocus.filters.common_tag },
+    display_notifications = false,
+    modifier='Super_L', keys={'Tab', 'ISO_Left_Tab'}
+}),
+```
+
+## Status
+
+Stable: it works well for me and others.
+Internals, default settings and behavior might still change.
+
+I came up with this while dipping my toes in the waters of awesome. If you have
+problems, please enable `cyclefocus.debug_level` (goes up to 3) and report your
+findings on the [Github issue tracker][].
+
+# Bugs, Feedback and Support
+
+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
+
+[awesome window manager]: http://awesome.naquadah.org/
+[Github issue tracker]: https://github.com/blueyed/awesome-cyclefocus/issues
diff --git a/config/awesome/cyclefocus/init.lua b/config/awesome/cyclefocus/init.lua
new file mode 100644
index 0000000..edb1691
--- /dev/null
+++ b/config/awesome/cyclefocus/init.lua
@@ -0,0 +1,1079 @@
+--- Cycle through recently focused clients (Alt-Tab and more).
+--
+-- Author: http://daniel.hahler.de
+-- Github: https://github.com/blueyed/awesome-cyclefocus
+
+local awful        = require('awful')
+-- local setmetatable = setmetatable
+local naughty      = require("naughty")
+local table        = table
+local tostring     = tostring
+local floor        = require("math").floor
+local capi         = {
+--     tag            = tag,
+    client         = client,
+    keygrabber     = keygrabber,
+--     mousegrabber   = mousegrabber,
+    mouse          = mouse,
+    screen         = screen,
+    awesome        = awesome,
+}
+local wibox        = require("wibox")
+
+local xresources = require("beautiful").xresources
+local dpi = xresources and xresources.apply_dpi or function() end
+
+--- Escape pango markup, taken from naughty.
+local escape_markup = function(s)
+    local escape_pattern = "[<>&]"
+    local escape_subs = { ['<'] = "&lt;", ['>'] = "&gt;", ['&'] = "&amp;" }
+    return s:gsub(escape_pattern, escape_subs)
+end
+
+
+-- Configuration. This can be overridden: global or via args to cyclefocus.cycle.
+local cyclefocus
+cyclefocus = {
+    -- 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 = 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_client_title(args.client, false))
+
+            preset.icon = cyclefocus.icon_loader(args.client.icon)
+        end,
+
+        -- Preset for current entry.
+        ["0"] = function (preset, args)
+            preset.font = 'sans 12'
+            preset.icon_size = 48
+            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 " .. 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
+    },
+
+    -- Default builtin filters.
+    -- (meant to get applied always, but you could override them)
+    cycle_filters = {
+        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.
+    -- XXX: needs to be also handled in request::activate then probably.
+    -- TODO: make this configurable during runtime of the binding, e.g. by
+    --       flagging entries in the stack or using different stacks.
+    -- 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.
+    filter_focus_history = awful.client.focus.filter,
+
+    -- Display notifications while cycling?
+    -- WARNING: without raise_clients this will not make sense probably!
+    display_notifications = true,
+
+    -- Debugging: messages get printed, and should show up in ~/.xsession-errors etc.
+    -- 1: enable, 2: verbose, 3: very verbose, 4: much verbose.
+    debug_level = 0,
+    -- Use naughty notifications for debugging (additional to printing)?
+    debug_use_naughty_notify = 1,
+}
+
+local has_gears, gears = pcall(require, 'gears')
+if has_gears then
+    -- Use gears to prevent memory leaking.
+    cyclefocus.icon_loader = gears.surface.load
+else
+    cyclefocus.icon_loader = function(icon) return icon end
+end
+
+-- A set of default filters, which can be used for cyclefocus.cycle_filters.
+cyclefocus.filters = {
+    -- Filter clients on the same screen.
+    same_screen = function (c, source_c)
+        return (c.screen or capi.mouse.screen) == source_c.screen
+    end,
+
+    same_class = function (c, source_c)
+        return c.class == source_c.class
+    end,
+
+    -- Only marked clients (via awful.client.mark and .unmark).
+    marked = function (c, source_c)  --luacheck: no unused args
+        return awful.client.ismarked(c)
+    end,
+
+    common_tag  = function (c, source_c)
+        if c == source_c then
+            return true
+        end
+        cyclefocus.debug("common_tag_filter\n"
+            .. cyclefocus.get_object_name(c) .. " <=> " .. cyclefocus.get_object_name(source_c), 3)
+        for _, t in pairs(c:tags()) do
+            for _, t2 in pairs(source_c:tags()) do
+                if t == t2 then
+                    cyclefocus.debug('common_tag_filter: client shares tag "'
+                        .. cyclefocus.get_object_name(t)
+                        .. '" with "' .. cyclefocus.get_object_name(c)..'"', 2)
+                    return true
+                end
+            end
+        end
+        return false
+    end,
+
+    -- EXPERIMENTAL:
+    -- Skip clients that were added through "focus" signal.
+    -- Replaces only_add_internal_focus_changes_to_history.
+    not_through_focus_signal = function (c, source_c)  --luacheck: no unused args
+        local attribs = cyclefocus.history.attribs(c)
+        return not attribs.source or attribs.source ~= "focus"
+    end,
+}
+
+local ignore_focus_signal = false  -- Flag to ignore the focus signal internally.
+local showing_client
+
+
+-- Debug function. Set focusstyle.debug to activate it. {{{
+cyclefocus.debug = function(msg, level)
+    level = level or 1
+    if not cyclefocus.debug_level or cyclefocus.debug_level < level then
+        return
+    end
+
+    if cyclefocus.debug_use_naughty_notify then
+        naughty.notify({
+            -- TODO: use indenting
+            -- text = tostring(msg)..' ['..tostring(level)..']',
+            text = tostring(msg),
+            timeout = 10,
+        })
+    end
+    print("cyclefocus: " .. msg)
+end
+
+local get_object_name = function (o)
+    if not o then
+        return '[no object]'
+    elseif not o.name then
+        return '[no object name]'
+    else
+        return o.name
+    end
+end
+cyclefocus.get_object_name = get_object_name
+
+
+cyclefocus.get_client_title = function (c, current)  --luacheck: no unused args
+    -- Use get_object_name to handle .name=nil.
+    local title = cyclefocus.get_object_name(c)
+    if #title > 80 then
+        title = title:sub(1, 80) .. '…'
+    end
+    return title
+end
+-- }}}
+
+
+-- Internal functions to handle the focus history. {{{
+-- Based on awful.client.focus.history.
+local history = {
+    stack = {}
+}
+
+--- Remove a client from the history stack.
+-- @tparam table Client.
+function history.delete(c)
+    local k = history._get_key(c)
+    if k then
+        table.remove(history.stack, k)
+    end
+end
+
+function history._get_key(c)
+    for k, v in ipairs(history.stack) do
+        if v[1] == c then
+            return k
+        end
+    end
+end
+
+function history.attribs(c)
+    local k = history._get_key(c)
+    if k then
+        return history.stack[k][2]
+    end
+end
+
+function history.clear()
+    history.stack = {}
+end
+
+-- @param filter: a function / boolean to filter clients: true means to add it.
+function history.add(c, filter, append, attribs)
+    filter = filter or cyclefocus.filter_focus_history
+    append = append or false
+    attribs = attribs or {}
+
+    -- Less verbose debugging during startup/restart.
+    cyclefocus.debug("history.add: " .. get_object_name(c), capi.awesome.startup and 4 or 2)
+
+    if filter and type(filter) == "function" then
+        if not filter(c) then
+            cyclefocus.debug("Filtered! " .. get_object_name(c), 2)
+            return true
+        end
+    end
+
+    -- Remove any existing entries from the stack.
+    history.delete(c)
+
+    if append then
+        table.insert(history.stack, {c, attribs})
+    else
+        table.insert(history.stack, 1, {c, attribs})
+    end
+
+    -- Manually add it to awesome's internal history (where we've removed the
+    -- signal from).
+    awful.client.focus.history.add(c)
+end
+
+function history.movetotop(c)
+    local attribs = history.attribs(c)
+    history.add(c, true, false, attribs)
+end
+
+function history.append(c, filter, attribs)
+    return history.add(c, filter, true, attribs)
+end
+
+--- Save the history into a X property.
+function history.persist()
+    local ids = {}
+    for _, v in ipairs(history.stack) do
+        table.insert(ids, v[1].window)
+    end
+    local xprop = table.concat(ids, " ")
+    capi.awesome.set_xproperty('awesome.cyclefocus.history', xprop)
+end
+
+--- Load history from the X property.
+function history.load()
+    local xprop = capi.awesome.get_xproperty('awesome.cyclefocus.history')
+    if not xprop or xprop == "" then
+        return
+    end
+
+    local cls = capi.client.get()
+    local ids = {}
+    for id in string.gmatch(xprop, "%S+") do
+        table.insert(ids, 1, id)
+    end
+    for _,window in ipairs(ids) do
+        for _,c in pairs(cls) do
+            if tonumber(window) == c.window then
+                history.add(c, true, false, {source="load"})
+                break
+            end
+        end
+    end
+end
+
+-- Persist history when restarting awesome.
+capi.awesome.register_xproperty('awesome.cyclefocus.history', 'string')
+capi.awesome.connect_signal("exit", function(restarting)
+    ignore_focus_signal = true
+    if restarting then
+        history.persist()
+    end
+end)
+
+-- On startup / restart: load the history and jump to the last focused client.
+cyclefocus.load_on_startup = function()
+    capi.awesome.disconnect_signal("refresh", cyclefocus.load_on_startup)
+
+    ignore_focus_signal = true
+    history.load()
+    if history.stack[1] then
+        showing_client = history.stack[1][1]
+        showing_client:jump_to()
+        showing_client = nil
+    end
+    ignore_focus_signal = false
+end
+capi.awesome.connect_signal("refresh", cyclefocus.load_on_startup)
+
+-- Export it. At least history.add should be.
+cyclefocus.history = history
+-- }}}
+
+-- Connect to signals. {{{
+-- Add clients that got focused to the history stack,
+-- but not when we are cycling through the clients ourselves.
+capi.client.connect_signal("focus", function (c)
+    if ignore_focus_signal or capi.awesome.startup then
+        cyclefocus.debug("Ignoring focus signal: " .. get_object_name(c), 4)
+        return
+    end
+    history.add(c, nil, nil, {source="focus"})
+end)
+
+-- Disable awesome's internal history handler to handle `ignore_focus_signal`.
+-- https://github.com/awesomeWM/awesome/pull/906.
+if awful.client.focus.history.disable_tracking then
+    awful.client.focus.history.disable_tracking()
+else
+    capi.client.disconnect_signal("focus", awful.client.focus.history.add)
+end
+
+capi.client.connect_signal("manage", function (c)
+    if ignore_focus_signal then
+        cyclefocus.debug("Ignoring focus signal (manage): " .. get_object_name(c), 2)
+        return
+    end
+
+    -- During startup: append any clients, to make them known,
+    -- but not override history.load etc.
+    if capi.awesome.startup then
+        history.append(c)
+    else
+        history.add(c, nil, false, {source="manage"})
+    end
+end)
+
+capi.client.connect_signal("unmanage", function (c)
+    history.delete(c)
+end)
+-- }}}
+
+-- Raise a client (does not include focusing).
+-- NOTE: awful.client.jumpto also focuses the screen / resets the mouse.
+-- See https://github.com/blueyed/awesome-cyclefocus/issues/6
+-- Based on awful.client.jumpto, without the code for mouse.
+-- Calls tag:viewonly always to update the tag history, also when
+-- the client is visible.
+local raise_client = function(c)
+    -- Try to make client visible, this also covers e.g. sticky
+    local t = c:tags()[1]
+    if t then
+        t:view_only()
+    end
+    c:jump_to()
+end
+
+
+-- Keep track of the client where "ontop" needs to be restored, and forget
+-- about it in "unmanage", to avoid an "invalid object" error.
+-- Ref: https://github.com/awesomeWM/awesome/issues/110
+local restore_ontop_c
+local restore_callback_show_client
+local show_client_restore_client_props = {}
+client.connect_signal("unmanage", function (c)
+    if restore_ontop_c and c == restore_ontop_c[1] then
+        restore_ontop_c = nil
+    end
+    if c == restore_callback_show_client then
+        restore_callback_show_client = nil
+    end
+    if c == showing_client then
+        showing_client = nil
+    end
+
+    if show_client_restore_client_props[c] then
+        show_client_restore_client_props[c] = nil
+    end
+end)
+
+
+local beautiful = require("beautiful")
+
+--- Callback to get properties for clients that are shown during cycling.
+-- @client c
+-- @return table
+cyclefocus.decorate_show_client = function(c)
+    return {
+        -- border_color = beautiful.fg_focus,
+        border_color = beautiful.border_focus,
+        border_width = c.border_width or 1,
+        -- XXX: changes layout / triggers resizes.
+        -- border_width = 10,
+    }
+end
+--- Callback to get properties for other clients that are visible during cycling.
+-- @client c
+-- @return table
+cyclefocus.decorate_show_client_others = function(c)  --luacheck: no unused args
+    return {
+        -- XXX: too distracting.
+        -- opacity = 0.7
+    }
+end
+
+local show_client_apply_props = {}
+
+local show_client_apply_props_others = {}
+local show_client_restore_client_props_others = {}
+
+local callback_show_client_lock
+local decorate_if_showing_client = function (c)
+    if c == showing_client then
+        cyclefocus.callback_show_client(c)
+    end
+end
+-- A table with property callbacks.  Could be merged with decorate_if_showing_client.
+local update_show_client_restore_client_props = {}
+--- Callback when a client gets shown during cycling.
+-- This can be overridden itself, but it's meant to be configured through
+-- decorate_show_client instead.
+-- @client c
+-- @param boolean Restore the previous state?
+cyclefocus.callback_show_client = function (c, restore)
+    if callback_show_client_lock then return end
+    callback_show_client_lock = true
+
+    if restore then
+        -- Restore all saved properties.
+        if show_client_restore_client_props[c] then
+            -- Disconnect signals.
+            for k,_ in pairs(show_client_restore_client_props[c]) do
+                client.disconnect_signal("property::" .. k, decorate_if_showing_client)
+                client.disconnect_signal("property::" .. k, update_show_client_restore_client_props[c][k])
+            end
+
+            for k,v in pairs(show_client_restore_client_props[c]) do
+                c[k] = v
+            end
+
+            -- Restore properties for other clients.
+            for _c,props in pairs(show_client_restore_client_props_others[c]) do
+                for k,v in pairs(props) do
+                    -- XXX: might have an "invalid object" here!
+                    _c[k] = v
+                end
+            end
+
+            show_client_apply_props[c] = nil
+            show_client_restore_client_props[c] = nil
+            show_client_restore_client_props_others[c] = nil
+        end
+    else
+        -- Save orig settings on first call.
+        local first_call = not show_client_restore_client_props[c]
+        if first_call then
+            show_client_restore_client_props[c] = {}
+            show_client_apply_props[c] = {}
+
+            -- Get props to apply and store original values.
+            show_client_apply_props[c] = cyclefocus.decorate_show_client(c)
+            update_show_client_restore_client_props[c] = {}
+            for k,_ in pairs(show_client_apply_props[c]) do
+                show_client_restore_client_props[c][k] = c[k]
+            end
+
+            -- Get props for other clients and store original values.
+            -- TODO: handle all screens?!
+            show_client_apply_props_others[c] = cyclefocus.decorate_show_client_others(c)
+            show_client_restore_client_props_others[c] = {}
+            for s in capi.screen do
+                for _,_c in pairs(awful.client.visible(s)) do
+                    if _c ~= c then
+                        show_client_restore_client_props_others[c][_c] = {}
+                        for k,_ in pairs(show_client_apply_props_others[c]) do
+                            show_client_restore_client_props_others[c][_c][k] = _c[k]
+                        end
+                    end
+                end
+            end
+        end
+        -- Apply props from callback.
+        for k,v in pairs(show_client_apply_props[c]) do
+            c[k] = v
+        end
+        -- Apply props for other clients.
+        for _c,_ in pairs(show_client_restore_client_props_others[c]) do
+            for k,v in pairs(show_client_apply_props_others[c]) do
+                _c[k] = v  -- see: XXX_1
+            end
+        end
+
+        if first_call then
+            for k,_ in pairs(show_client_apply_props[c]) do
+                client.connect_signal("property::" .. k, decorate_if_showing_client)
+
+                -- Update client props to be restored during showing a client,
+                -- e.g. border_color from focus signals.
+                update_show_client_restore_client_props[c][k] = function()
+                    show_client_restore_client_props[c][k] = c[k]
+                end
+                client.connect_signal("property::" .. k, update_show_client_restore_client_props[c][k])
+            end
+            -- TODO: merge with above; also disconnect on restore.
+            -- for k,v in pairs(show_client_apply_props_others[c]) do
+            --     client.connect_signal("property::" .. k, decorate_if_showing_client)
+            -- end
+        end
+    end
+
+    callback_show_client_lock = false
+end
+
+-- Helper function to restore state of the temporarily selected client.
+cyclefocus.show_client = function (c)
+    showing_client = c
+
+    if c then
+        if restore_callback_show_client then
+            cyclefocus.callback_show_client(restore_callback_show_client, true)
+        end
+        restore_callback_show_client = c
+
+        -- (Re)store ontop property.
+        if restore_ontop_c then
+            restore_ontop_c[1].ontop = restore_ontop_c[2]
+        end
+        restore_ontop_c = {c, c.ontop}
+        c.ontop = true
+
+        -- Make the clients tag visible, if it currently is not.
+        local sel_tags = c.screen.selected_tags
+        local c_tag = c.first_tag or c:tags()[1]
+        if not awful.util.table.hasitem(sel_tags, c_tag) then
+            -- Select only the client's first tag, after de-selecting
+            -- all others.
+
+            -- Make the client sticky temporarily, so it will be
+            -- considered visbile internally.
+            -- NOTE: this is done for client_maybevisible (used by autofocus).
+            local restore_sticky = c.sticky
+            c.sticky = true
+
+            for _, t in pairs(c.screen.tags) do
+                if t ~= c_tag then
+                    t.selected = false
+                end
+            end
+            c_tag.selected = true
+
+            -- Restore.
+            c.sticky = restore_sticky
+        end
+        cyclefocus.callback_show_client(c, false)
+
+    else  -- No client provided, restore only.
+        if restore_ontop_c then
+            restore_ontop_c[1].ontop = restore_ontop_c[2]
+        end
+        cyclefocus.callback_show_client(restore_callback_show_client, true)
+        showing_client = nil
+    end
+end
+
+--- Cached main wibox.
+local wbox
+local wbox_screen
+local layout
+
+-- Main function.
+cyclefocus.cycle = function(startdirection_or_args, args)
+    if type(startdirection_or_args) == 'number' then
+        awful.util.deprecate('startdirection is not used anymore: pass in args only', {raw=true})
+    else
+        args = startdirection_or_args
+    end
+    args = awful.util.table.join(awful.util.table.clone(cyclefocus), args)
+    -- The key name of the (last) modifier: this gets used for the "release" event.
+    local modifier = args.modifier or 'Alt_L'
+    local keys = args.keys or {'Tab', 'ISO_Left_Tab'}
+    local shift = args.shift or 'Shift'
+    -- cycle_filters: merge with defaults from module.
+    local cycle_filters = awful.util.table.join(args.cycle_filters or {},
+        cyclefocus.cycle_filters)
+
+    local filter_result_cache = {}     -- Holds cached filter results.
+
+    local show_clients = args.show_clients
+    if show_clients and type(show_clients) ~= 'function' then
+        show_clients = cyclefocus.show_client
+    end
+
+    -- Support single filter.
+    if args.cycle_filter then
+        cycle_filters = awful.util.table.clone(cycle_filters)
+        table.insert(cycle_filters, args.cycle_filter)
+    end
+
+    -- Set flag to ignore any focus events while cycling through clients.
+    ignore_focus_signal = true
+
+    -- Internal state.
+    local orig_client = capi.client.focus  -- Will be jumped to via Escape (abort).
+
+    -- Save list of selected tags for all screens.
+    local restore_tag_selected = {}
+    for s in capi.screen do
+        restore_tag_selected[s] = {}
+        for _,t in pairs(s.tags) do
+            restore_tag_selected[s][t] = t.selected
+        end
+    end
+
+    --- Helper function to get the next client.
+    -- @param direction 1 (forward) or -1 (backward).
+    -- @param idx Current index in the stack.
+    -- @param stack Current stack (default: history.stack).
+    -- @param consider_cur_idx Also look at the current idx, and consider it
+    --                         when it's not focused.
+    -- @return client or nil and current index in stack.
+    local get_next_client = function(direction, idx, stack, consider_cur_idx)
+        local startidx = idx
+        stack = stack or history.stack
+        consider_cur_idx = consider_cur_idx or args.focus_clients
+
+        local nextc
+
+        cyclefocus.debug('get_next_client: #' .. idx .. ", dir=" .. direction
+            .. ", start=" .. startidx .. ", consider_cur=" .. tostring(consider_cur_idx), 2)
+
+        local n = #stack
+        if consider_cur_idx then
+            local c_top = stack[idx][1]
+            if c_top ~= capi.client.focus then
+                n = n+1
+                cyclefocus.debug("Considering nextc from top of stack: " .. tostring(c_top), 2)
+            else
+                consider_cur_idx = false
+            end
+        end
+        for loop_stack_i = 1, n do
+            if not consider_cur_idx or loop_stack_i ~= 1 then
+                idx = idx + direction
+                if idx < 1 then
+                    idx = #stack
+                elseif idx > #stack then
+                    idx = 1
+                end
+            end
+            cyclefocus.debug('find loop: #' .. idx .. ", dir=" .. direction, 3)
+            nextc = stack[idx][1]
+
+            if nextc then
+                -- Filtering.
+                if cycle_filters then
+                    -- Get and init filter cache data structure. {{{
+                    -- TODO: move function(s) up?
+                    local get_cached_filter_result = function(f, a, b)
+                        b = b or false  -- handle nil
+                        if filter_result_cache[f] == nil then
+                            filter_result_cache[f] = { [a] = { [b] = { } } }
+                            return nil
+                        elseif filter_result_cache[f][a] == nil then
+                            filter_result_cache[f][a] = { [b] = { } }
+                            return nil
+                        elseif filter_result_cache[f][a][b] == nil then
+                            return nil
+                        end
+                        return filter_result_cache[f][a][b]
+                    end
+                    local set_cached_filter_result = function(f, a, b, value)
+                        b = b or false  -- handle nil
+                        get_cached_filter_result(f, a, b)  -- init
+                        filter_result_cache[f][a][b] = value
+                    end -- }}}
+
+                    -- Apply filters, while looking up cache.
+                    local filter_result
+                    for _k, filter in pairs(cycle_filters) do
+                        cyclefocus.debug("Checking filter ".._k.."/"..#cycle_filters..": "..tostring(filter), 4)
+                        filter_result = get_cached_filter_result(filter, nextc, args.initiating_client)
+                        if filter_result ~= nil then
+                            if not filter_result then
+                                nextc = false
+                                break
+                            end
+                        else
+                            filter_result = filter(nextc, args.initiating_client)
+                            set_cached_filter_result(filter, nextc, args.initiating_client, filter_result)
+                            if not filter_result then
+                                cyclefocus.debug("Filtering/skipping client: " .. get_object_name(nextc), 3)
+                                nextc = false
+                                break
+                            end
+                        end
+                    end
+                end
+                if nextc then
+                    -- Found client to switch to.
+                    break
+                end
+            end
+        end
+        cyclefocus.debug("get_next_client returns: " .. get_object_name(nextc) .. ', idx=' .. idx, 1)
+        return nextc, idx
+    end
+
+    local first_run = true
+    local nextc
+    local idx = 1  -- Currently focused client in the stack.
+
+    -- Get the screen before moving the mouse.
+    local initial_screen = awful.screen.focused and awful.screen.focused() or mouse.screen
+
+    -- Move mouse pointer away to avoid sloppy focus kicking in.
+    local restore_mouse_coords
+    if show_clients then
+        local s = capi.screen[capi.mouse.screen]
+        local coords = capi.mouse.coords()
+        restore_mouse_coords = {s = s, x = coords.x, y = coords.y}
+        local pos = {x = s.geometry.x, y = s.geometry.y}
+        -- move cursor without triggering signals mouse::enter and mouse::leave
+        capi.mouse.coords(pos, true)
+        restore_mouse_coords.moved = pos
+    end
+
+    capi.keygrabber.run(function(mod, key, event)
+        -- Helper function to exit out of the keygrabber.
+        -- If a client is given, it will be jumped to.
+        local exit_grabber = function(c)
+            cyclefocus.debug("exit_grabber: " .. get_object_name(c), 2)
+            if wbox then
+                wbox.visible = false
+            end
+            capi.keygrabber.stop()
+
+            -- Restore.
+            if show_clients then
+                show_clients()
+            end
+
+            -- Restore previously selected tags for screen(s).
+            -- With a given client, handle other screens first, otherwise
+            -- the focus might be on the wrong screen.
+            if restore_tag_selected then
+                for s in capi.screen do
+                    if not c or s ~= c.screen then
+                        for _,t in pairs(s.tags) do
+                            t.selected = restore_tag_selected[s][t]
+                        end
+                    end
+                end
+            end
+
+            -- Restore mouse if it has not been moved during cycling.
+            if restore_mouse_coords then
+                if restore_mouse_coords.s == capi.screen[capi.mouse.screen] then
+                  local coords = capi.mouse.coords()
+                  local moved_coords = restore_mouse_coords.moved
+                  if moved_coords.x == coords.x and moved_coords.y == coords.y then
+                      capi.mouse.coords({x = restore_mouse_coords.x, y = restore_mouse_coords.y}, true)
+                  end
+                end
+            end
+
+            if c then
+                showing_client = c
+                raise_client(c)
+                if c ~= orig_client then
+                    history.movetotop(c)
+                end
+            end
+            ignore_focus_signal = false
+
+            return true
+        end
+
+        cyclefocus.debug("grabber: mod: " .. table.concat(mod, ',')
+            .. ", key: " .. tostring(key)
+            .. ", event: " .. tostring(event)
+            .. ", modifier_key: " .. tostring(modifier), 3)
+
+        -- Abort on Escape.
+        if key == 'Escape' then
+            return exit_grabber(orig_client)
+        end
+
+        -- Direction (forward/backward) is determined by status of shift.
+        local direction = awful.util.table.hasitem(mod, shift) and -1 or 1
+
+        if event == "release" and key == modifier then
+            -- Focus selected client when releasing modifier.
+            -- When coming here on first run, the trigger was pressed quick and
+            -- we need to fetch the next client while exiting.
+            if first_run then
+                nextc, idx = get_next_client(direction, idx)
+            end
+            if show_clients then
+                show_clients(nextc)
+            end
+            return exit_grabber(nextc)
+        end
+
+        -- Ignore any "release" events and unexpected keys, except for the first run.
+        if not first_run then
+            if not awful.util.table.hasitem(keys, key) then
+                cyclefocus.debug("Ignoring unexpected key: " .. tostring(key), 1)
+                return true
+            end
+            if event == "release" then
+                return true
+            end
+        end
+        first_run = false
+
+        nextc, idx = get_next_client(direction, idx)
+        if not nextc then
+            return exit_grabber()
+        end
+
+        -- Show the client, which triggers setup of restore_callback_show_client etc.
+        if show_clients then
+            show_clients(nextc)
+        end
+        -- Focus client.
+        if args.focus_clients then
+            capi.client.focus = nextc
+        end
+
+        if not args.display_notifications then
+            return true
+        end
+
+        local container_margin_top_bottom = dpi(5)
+        local container_margin_left_right = dpi(5)
+        if not wbox then
+            wbox = wibox({ontop = true })
+            wbox._for_screen = mouse.screen
+            wbox:set_fg(beautiful.fg_normal)
+            wbox:set_bg("#ffffff00")
+
+            local container_inner = wibox.layout.align.vertical()
+            local container_layout = wibox.container.margin(
+                container_inner,
+                container_margin_left_right, container_margin_left_right,
+                container_margin_top_bottom, container_margin_top_bottom)
+            container_layout = wibox.container.background(container_layout)
+            container_layout:set_bg(beautiful.bg_normal..'cc')
+
+            -- constraint:set_widget(layout)
+            -- constraint = wibox.layout.constraint(layout, "max", w, h/2)
+            -- wbox:set_widget(constraint)
+            wbox:set_widget(container_layout)
+            layout = wibox.layout.flex.vertical()
+            container_inner:set_middle(layout)
+        else
+            layout:reset()
+        end
+
+        -- Set geometry always, the screen might have changed.
+        if not wbox_screen or wbox_screen ~= initial_screen then
+            wbox_screen = initial_screen
+            local wa = screen[wbox_screen].workarea
+            local w = math.ceil(wa.width * 0.618)
+            wbox:geometry({
+                -- right-align.
+                x = math.ceil(wa.x + wa.width - w),
+                width = w,
+            })
+        end
+        local wbox_height = 0
+        local max_icon_size = 48
+
+        -- Create entry with index, name and screen.
+        local display_entry_for_idx_offset = function(offset, c, _idx, displayed_list)  -- {{{
+            local preset = awful.util.table.clone(args.default_preset)
+
+            -- Callback.
+            local args_for_cb = {
+                client=c,
+                offset=offset,
+                idx=_idx,
+                displayed_list=displayed_list }
+            local preset_for_offset = args.preset_for_offset
+            local preset_cb = preset_for_offset[tostring(offset)]
+            -- Callback for all.
+            if preset_for_offset.default then
+                preset_for_offset.default(preset, args_for_cb)
+            end
+            -- Callback for offset.
+            if preset_cb then
+                preset_cb(preset, args_for_cb)
+            end
+
+            -- local entry_layout = wibox.layout.flex.horizontal()
+            local entry_layout = wibox.layout.fixed.horizontal()
+
+            -- From naughty.
+            local icon = preset.icon
+            local icon_margin = 5
+            local iconmarginbox
+            if icon then
+                local cairo = require("lgi").cairo
+                local iconbox = wibox.widget.imagebox()
+                local icon_size = preset.icon_size
+                if icon_size then
+                    local scaled = cairo.ImageSurface(cairo.Format.ARGB32, icon_size, icon_size)
+                    local cr = cairo.Context(scaled)
+                    cr:scale(icon_size / icon:get_height(), icon_size / icon:get_width())
+                    cr:set_source_surface(icon, 0, 0)
+                    cr:paint()
+                    icon = scaled
+                    icon_margin = icon_margin + math.max(0, (max_icon_size - icon_size)/2)
+                end
+
+                -- Margin.
+                iconmarginbox = wibox.container.margin(iconbox)
+                iconmarginbox:set_margins(icon_margin)
+
+                iconbox:set_resize(false)
+                iconbox:set_image(icon)
+
+                entry_layout:add(iconmarginbox)
+            end
+
+            local textbox = wibox.widget.textbox()
+            textbox:set_markup(preset.text)
+            textbox:set_font(preset.font)
+            textbox:set_wrap("word_char")
+            textbox:set_ellipsize("middle")
+            local textbox_margin = wibox.container.margin(textbox)
+            textbox_margin:set_margins(dpi(5))
+
+            entry_layout:add(textbox_margin)
+            entry_layout = wibox.container.margin(entry_layout, dpi(5), dpi(5),
+                                               dpi(2), dpi(2))
+            local entry_with_bg = wibox.container.background(entry_layout)
+            if offset == 0 then
+                entry_with_bg:set_fg(beautiful.fg_focus)
+                entry_with_bg:set_bg(beautiful.bg_focus)
+            else
+                entry_with_bg:set_fg(beautiful.fg_normal)
+                -- entry_with_bg:set_bg(beautiful.bg_normal.."dd")
+            end
+            layout:add(entry_with_bg)
+
+            -- Add height to outer wibox.
+            local context = {dpi=beautiful.xresources.get_dpi(initial_screen)}
+            local _, h = entry_with_bg:fit(context, wbox.width, 2^20)
+            wbox_height = wbox_height + h
+        end  -- }}}
+
+        -- Get clients before and after currently selected one.
+        local prevnextlist = awful.util.table.clone(history.stack)  -- Use a copy, entries will get nil'ed.
+        local _idx = idx
+
+        local dlist = {}  -- A table with offset => stack index.
+
+        dlist[0] = _idx
+        prevnextlist[_idx][1] = false
+
+        -- Build dlist for both directions, depending on how many entries should get displayed.
+        for _,dir in ipairs({1, -1}) do
+            _idx = dlist[0]
+            local n = dir == 1 and args.display_next_count or args.display_prev_count
+            for i = 1, n do
+                local _i = i * dir
+                _, _idx = get_next_client(dir, _idx, prevnextlist, false)
+                if _ then
+                    dlist[_i] = _idx
+                end
+                prevnextlist[_idx][1] = false
+            end
+        end
+
+        -- Sort the offsets.
+        local offsets = {}
+        for n in pairs(dlist) do table.insert(offsets, n) end
+        table.sort(offsets)
+
+        -- Display the wibox.
+        for _,i in ipairs(offsets) do
+            _idx = dlist[i]
+            display_entry_for_idx_offset(i, history.stack[_idx][1], _idx, dlist)
+        end
+        local wa = screen[initial_screen].workarea
+        local h = wbox_height + container_margin_top_bottom*2
+        wbox:geometry({
+            height = h,
+            y = wa.y + floor(wa.height/2 - h/2),
+        })
+        wbox.visible = true
+        return true
+    end)
+end
+
+
+-- A helper method to wrap awful.key.
+function cyclefocus.key(mods, key, startdirection_or_args, args)
+    mods = mods or {modkey} or {"Mod4"}
+    key = key or "Tab"
+    if type(startdirection_or_args) == 'number' then
+        awful.util.deprecate('startdirection is not used anymore: pass in mods, key, args', {raw=true})
+    else
+        args = startdirection_or_args
+    end
+    args = awful.util.table.clone(args) or {}
+    if not args.keys then
+        if key == "Tab" then
+            args.keys = {"Tab", "ISO_Left_Tab"}
+        else
+            args.keys = {key}
+        end
+    end
+    args.keys = args.keys or {key}
+    args.modifier = args.modifier or mods[0]
+
+    return awful.key(mods, key, function(c)
+        args.initiating_client = c  -- only for clientkeys, might be nil!
+        cyclefocus.cycle(args)
+    end)
+end
+
+return cyclefocus
diff --git a/config/awesome/cyclefocus/screenshot.png b/config/awesome/cyclefocus/screenshot.png
new file mode 100644
index 0000000..aa212b7
--- /dev/null
+++ b/config/awesome/cyclefocus/screenshot.png
diff --git a/config/awesome/rc.lua b/config/awesome/rc.lua
index 98f5fde..bbc4eea 100644
--- a/config/awesome/rc.lua
+++ b/config/awesome/rc.lua
@@ -11,6 +11,8 @@ local beautiful = require("beautiful")
 local naughty = require("naughty")
 local menubar = require("menubar")
 
+local cyclefocus = require("cyclefocus")
+
 -- Load Debian menu entries
 require("debian.menu")
 require("volume")
@@ -251,13 +253,21 @@ globalkeys = awful.util.table.join(
     awful.key({ modkey, "Control" }, "j", function () awful.screen.focus_relative( 1) end),
     awful.key({ modkey, "Control" }, "k", function () awful.screen.focus_relative(-1) end),
     awful.key({ modkey,           }, "u", awful.client.urgent.jumpto),
-    awful.key({ modkey,           }, "Tab",
-        function ()
-            awful.client.focus.history.previous()
-            if client.focus then
-                client.focus:raise()
-            end
-        end),
+    --awful.key({ modkey,           }, "Tab",
+    --    function ()
+    --        awful.client.focus.history.previous()
+    --        if client.focus then
+    --            client.focus:raise()
+    --        end
+    --    end),
+
+    --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({modifier="Super_L"})
+    --end),
 
     -- Standard program
     -- awful.key({ modkey,           }, "Return", function () awful.spawn(terminal) end),
@@ -510,6 +520,18 @@ clientkeys = awful.util.table.join(
             -- end
         end),
 
+    -- This must be a clientkeys mapping to have source_c available in the callback.
+    cyclefocus.key({ modkey }, "Tab", {
+        -- cycle_filters as a function callback:
+        -- cycle_filters = { function (c, source_c) return c.screen == source_c.screen end },
+
+        -- cycle_filters from the default filters:
+        --cycle_filters = { cyclefocus.filters.same_screen, cyclefocus.filters.common_tag },
+        cycle_filters = { cyclefocus.filters.same_screen },
+        modifier="Super_L",
+        keys = {'Tab', 'ISO_Left_Tab'}  -- default, could be left out
+    }),
+
     awful.key({ "Mod1"            }, "Up"   , function (c) c:raise() end),
     awful.key({ "Mod1"            }, "Down" , function (c) c:lower() end),
     awful.key({ modkey            }, ";"    , function (c) c:raise() end),